From cb2a2486429f163321bc5ff2208ea2137188a8e1 Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Wed, 13 Dec 2017 16:35:35 -0500 Subject: [PATCH 1/8] updates to build.cmd and readme --- README.md | 14 +++++++++----- build.cmd | 18 ++++++++++++++++-- 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 49891c8e0..30eac9d4e 100644 --- a/README.md +++ b/README.md @@ -3,22 +3,24 @@ # OpenAPI.NET [Preview] [ Disclaimer: This repository is in a preview state. Expect to see some iterating as we work towards the final release candidate slated for early 2018. Feedback is welcome! ] -The **OpenAPI.NET** SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OAI JSON and YAML documents from the model. +The **OpenAPI.NET** SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OpenAPI JSON and YAML documents from the model. **See more information on the Open API spec and its history here: Open API Initiative** Project Objectives -- Provide a single shared object model in .NET for Open API documents. -- Include the most primitive Reader for ingesting OAI JSON and YAML documents. -- Enable developers to create Readers that translate different data formats into Open API documents. +- Provide a single shared object model in .NET for OpenAPI descriptions. +- Include the most primitive Reader for ingesting OAI JSON and YAML documents in both V2 and V3 formats. +- Provide OpenAPI description writers for both V2 and V3 specification formats. +- Enable developers to create Readers that translate different data formats into OpenAPI descriptions. # Readers -The OpenAPI.NET project holds the base object model for representing OAI documents as .NET objects. Translation for different data types into this object model is handled by reading raw JSON/YAML or from individual "Readers", a number of which are in the works. +The OpenAPI.NET project holds the base object model for representing OpenAPI descriptions as .NET objects. Translation for different data types into this object model is handled by reading raw JSON/YAML or from individual "Readers", a number of which are in the works. The base JSON and YAML Readers are built into this project. Below is the list of supported "reader" projects. - .NET Comment Reader: [Coming Soon] +- OData (CSDL) Reader: [Comming Soon] # Build Status @@ -39,3 +41,5 @@ provided by the bot. You will only need to do this once across all repos using o This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +To provide feedback and ask questions you can use StackOverflow in the [OpenApi.net](https://stackoverflow.com/questions/tagged/openapi.net) tag or use the Slack OpenApi.net Slack channel which you can register for at http://slack.httpapis.com \ No newline at end of file diff --git a/build.cmd b/build.cmd index b741b8a90..d0d68b5d7 100644 --- a/build.cmd +++ b/build.cmd @@ -1,10 +1,24 @@ -SET VERSION=0.9.1 +@echo off +if "%~1"=="" goto :error + +SET %VERSION%=%~1 + +Echo Building Microsoft.OpenApi + SET PROJ=%~dp0src\Microsoft.OpenApi\Microsoft.OpenApi.csproj msbuild %PROJ% /t:restore /p:Configuration=Release msbuild %PROJ% /t:build /p:Configuration=Release msbuild %PROJ% /t:pack /p:Configuration=Release;PackageOutputPath=%~dp0artifacts;Version=%VERSION% +Echo Building Microsoft.OpenApi.Readers + SET PROJ=%~dp0src\Microsoft.OpenApi.Readers\Microsoft.OpenApi.Readers.csproj msbuild %PROJ% /t:restore /p:Configuration=Release msbuild %PROJ% /t:build /p:Configuration=Release -msbuild %PROJ% /t:pack /p:Configuration=Release;PackageOutputPath=%~dp0artifacts;Version=%VERSION% \ No newline at end of file +msbuild %PROJ% /t:pack /p:Configuration=Release;PackageOutputPath=%~dp0artifacts;Version=%VERSION% + +goto :end +:error +echo Version parameter missing e.g. build.cmd 1.0.0-beta0008 + +:end From 7212aa3e6e4099178c5ba5a47af8243f7897901f Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Wed, 13 Dec 2017 17:24:24 -0500 Subject: [PATCH 2/8] Added examples --- README.md | 69 ++++++++++++++- .../V3Tests/OpenApiReadmeTests.cs | 84 +++++++++++++++++++ 2 files changed, 152 insertions(+), 1 deletion(-) create mode 100644 test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiReadmeTests.cs diff --git a/README.md b/README.md index 30eac9d4e..d8aba766b 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ The **OpenAPI.NET** SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OpenAPI JSON and YAML documents from the model. -**See more information on the Open API spec and its history here: Open API Initiative** +**See more information on the OpenAPI spec and its history here: OpenAPI Initiative** Project Objectives @@ -22,6 +22,73 @@ The base JSON and YAML Readers are built into this project. Below is the list of - .NET Comment Reader: [Coming Soon] - OData (CSDL) Reader: [Comming Soon] +# Example Usage + +Creating a OpenAPI Document + +```Csharp +var document = new OpenApiDocument +{ + Info = new OpenApiInfo + { + Version = "1.0.0", + Title = "Swagger Petstore (Simple)", + }, + Servers = new List + { + new OpenApiServer { Url = "http://petstore.swagger.io/api" } + }, + Paths = new OpenApiPaths + { + ["/pets"] = new OpenApiPathItem + { + Operations = new Dictionary + { + [OperationType.Get] = new OpenApiOperation + { + Description = "Returns all pets from the system that the user has access to", + Responses = new OpenApiResponses + { + ["200"] = new OpenApiResponse + { + Description = "OK" + } + } + } + } + } + } +}; +``` + +Reading and writing a OpenAPI description + +``` CSharp +var httpClient = new HttpClient +{ + BaseAddress = new Uri("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/") +}; + +var stream = await httpClient.GetStreamAsync("master/examples/v3.0/petstore.yaml"); + +// Read V3 as YAML +var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostics); + +var outputStringWriter = new StringWriter(); +var writer = new OpenApiJsonWriter(outputStringWriter); + +// Write V2 as JSON +openApiDocument.SerializeAsV2(writer); + +outputStringWriter.Flush(); +var output = outputStringWriter.GetStringBuilder().ToString(); + +Assert.Empty(diagnostics.Errors); +Assert.NotNull(openApiDocument); +Assert.NotEmpty(output); + +``` + # Build Status |**master**| diff --git a/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiReadmeTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiReadmeTests.cs new file mode 100644 index 000000000..6a54ad24a --- /dev/null +++ b/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiReadmeTests.cs @@ -0,0 +1,84 @@ +using Microsoft.OpenApi.Models; +using Microsoft.OpenApi.Writers; +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Net.Http; +using System.Text; +using System.Threading.Tasks; +using Xunit; + +namespace Microsoft.OpenApi.Readers.Tests.V3Tests +{ + public class OpenApiReadmeTests + { + + [Fact] + public void CreatingADocumentTest() + { + var document = new OpenApiDocument + { + Info = new OpenApiInfo + { + Version = "1.0.0", + Title = "Swagger Petstore (Simple)", + }, + Servers = new List + { + new OpenApiServer { Url = "http://petstore.swagger.io/api" } + }, + Paths = new OpenApiPaths + { + ["/pets"] = new OpenApiPathItem + { + Operations = new Dictionary + { + [OperationType.Get] = new OpenApiOperation + { + Description = "Returns all pets from the system that the user has access to", + Responses = new OpenApiResponses + { + ["200"] = new OpenApiResponse + { + Description = "OK" + } + } + } + } + } + } + }; + + Assert.NotNull(document); + } + + [Fact] + public async Task ReadingAndWritingADocument() + { + var httpClient = new HttpClient + { + BaseAddress = new Uri("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/") + }; + + var stream = await httpClient.GetStreamAsync("master/examples/v3.0/petstore.yaml"); + + // Read V3 as YAML + var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostics); + + var outputStringWriter = new StringWriter(); + var writer = new OpenApiJsonWriter(outputStringWriter); + + // Write V2 as JSON + openApiDocument.SerializeAsV2(writer); + + outputStringWriter.Flush(); + var output = outputStringWriter.GetStringBuilder().ToString(); + + Assert.Empty(diagnostics.Errors); + Assert.NotNull(openApiDocument); + Assert.NotEmpty(output); + + } + } +} From 5be504bcbc34b77b75a610a89874657c0de858cc Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Wed, 13 Dec 2017 17:26:27 -0500 Subject: [PATCH 3/8] Fixed an OAI reference --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d8aba766b..76b6f5619 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The **OpenAPI.NET** SDK contains a useful object model for OpenAPI documents in Project Objectives - Provide a single shared object model in .NET for OpenAPI descriptions. -- Include the most primitive Reader for ingesting OAI JSON and YAML documents in both V2 and V3 formats. +- Include the most primitive Reader for ingesting OpenAPI JSON and YAML documents in both V2 and V3 formats. - Provide OpenAPI description writers for both V2 and V3 specification formats. - Enable developers to create Readers that translate different data formats into OpenAPI descriptions. From 0a633520ee0936ba4492e99078424cd745c07633 Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Wed, 13 Dec 2017 17:52:20 -0500 Subject: [PATCH 4/8] Removed readme tests --- .../V3Tests/OpenApiReadmeTests.cs | 84 ------------------- 1 file changed, 84 deletions(-) delete mode 100644 test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiReadmeTests.cs diff --git a/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiReadmeTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiReadmeTests.cs deleted file mode 100644 index 6a54ad24a..000000000 --- a/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiReadmeTests.cs +++ /dev/null @@ -1,84 +0,0 @@ -using Microsoft.OpenApi.Models; -using Microsoft.OpenApi.Writers; -using System; -using System.Collections.Generic; -using System.IO; -using System.Linq; -using System.Net.Http; -using System.Text; -using System.Threading.Tasks; -using Xunit; - -namespace Microsoft.OpenApi.Readers.Tests.V3Tests -{ - public class OpenApiReadmeTests - { - - [Fact] - public void CreatingADocumentTest() - { - var document = new OpenApiDocument - { - Info = new OpenApiInfo - { - Version = "1.0.0", - Title = "Swagger Petstore (Simple)", - }, - Servers = new List - { - new OpenApiServer { Url = "http://petstore.swagger.io/api" } - }, - Paths = new OpenApiPaths - { - ["/pets"] = new OpenApiPathItem - { - Operations = new Dictionary - { - [OperationType.Get] = new OpenApiOperation - { - Description = "Returns all pets from the system that the user has access to", - Responses = new OpenApiResponses - { - ["200"] = new OpenApiResponse - { - Description = "OK" - } - } - } - } - } - } - }; - - Assert.NotNull(document); - } - - [Fact] - public async Task ReadingAndWritingADocument() - { - var httpClient = new HttpClient - { - BaseAddress = new Uri("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/") - }; - - var stream = await httpClient.GetStreamAsync("master/examples/v3.0/petstore.yaml"); - - // Read V3 as YAML - var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostics); - - var outputStringWriter = new StringWriter(); - var writer = new OpenApiJsonWriter(outputStringWriter); - - // Write V2 as JSON - openApiDocument.SerializeAsV2(writer); - - outputStringWriter.Flush(); - var output = outputStringWriter.GetStringBuilder().ToString(); - - Assert.Empty(diagnostics.Errors); - Assert.NotNull(openApiDocument); - Assert.NotEmpty(output); - - } - } -} From 79649750ba326e12abdf50f724a2a01a1e02c2aa Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Wed, 13 Dec 2017 18:15:10 -0500 Subject: [PATCH 5/8] Fixed issues based on PR reviews --- README.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 76b6f5619..715823158 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ The **OpenAPI.NET** SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OpenAPI JSON and YAML documents from the model. -**See more information on the OpenAPI spec and its history here: OpenAPI Initiative** +**See more information on the OpenAPI spec and its history here: Open API Initiative** Project Objectives @@ -20,13 +20,13 @@ The OpenAPI.NET project holds the base object model for representing OpenAPI des The base JSON and YAML Readers are built into this project. Below is the list of supported "reader" projects. - .NET Comment Reader: [Coming Soon] -- OData (CSDL) Reader: [Comming Soon] +- OData (CSDL) Reader: [Coming Soon] # Example Usage -Creating a OpenAPI Document +Creating an OpenAPI Document -```Csharp +```C# var document = new OpenApiDocument { Info = new OpenApiInfo @@ -63,7 +63,7 @@ var document = new OpenApiDocument Reading and writing a OpenAPI description -``` CSharp +```C# var httpClient = new HttpClient { BaseAddress = new Uri("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/") @@ -72,7 +72,7 @@ var httpClient = new HttpClient var stream = await httpClient.GetStreamAsync("master/examples/v3.0/petstore.yaml"); // Read V3 as YAML -var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostics); +var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostic); var outputStringWriter = new StringWriter(); var writer = new OpenApiJsonWriter(outputStringWriter); @@ -83,10 +83,6 @@ openApiDocument.SerializeAsV2(writer); outputStringWriter.Flush(); var output = outputStringWriter.GetStringBuilder().ToString(); -Assert.Empty(diagnostics.Errors); -Assert.NotNull(openApiDocument); -Assert.NotEmpty(output); - ``` # Build Status @@ -109,4 +105,4 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. -To provide feedback and ask questions you can use StackOverflow in the [OpenApi.net](https://stackoverflow.com/questions/tagged/openapi.net) tag or use the Slack OpenApi.net Slack channel which you can register for at http://slack.httpapis.com \ No newline at end of file +To provide feedback and ask questions you can use StackOverflow with the [OpenApi.net](https://stackoverflow.com/questions/tagged/openapi.net) tag or use the OpenApi.net Slack channel which you can register for at http://slack.httpapis.com \ No newline at end of file From 91a88369a117f1c13ce43e814b00a06eddf98f0f Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Wed, 13 Dec 2017 18:17:49 -0500 Subject: [PATCH 6/8] Added note about slack team --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 715823158..e11e83f38 100644 --- a/README.md +++ b/README.md @@ -105,4 +105,4 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. -To provide feedback and ask questions you can use StackOverflow with the [OpenApi.net](https://stackoverflow.com/questions/tagged/openapi.net) tag or use the OpenApi.net Slack channel which you can register for at http://slack.httpapis.com \ No newline at end of file +To provide feedback and ask questions you can use StackOverflow with the [OpenApi.net](https://stackoverflow.com/questions/tagged/openapi.net) tag or use the OpenApi.net Slack channel which you can register for the httpapis team at http://slack.httpapis.com \ No newline at end of file From 393c78cd092a1b99bb764a612580e05a15b31801 Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Wed, 13 Dec 2017 18:19:15 -0500 Subject: [PATCH 7/8] Words are hard --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e11e83f38..61850d92f 100644 --- a/README.md +++ b/README.md @@ -105,4 +105,4 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. -To provide feedback and ask questions you can use StackOverflow with the [OpenApi.net](https://stackoverflow.com/questions/tagged/openapi.net) tag or use the OpenApi.net Slack channel which you can register for the httpapis team at http://slack.httpapis.com \ No newline at end of file +To provide feedback and ask questions you can use StackOverflow with the [OpenApi.net](https://stackoverflow.com/questions/tagged/openapi.net) tag or use the OpenApi.net Slack channel which you can join by registering for the httpapis team at http://slack.httpapis.com \ No newline at end of file From 479e6c7ce4214941dc3c215526de6185337af3d7 Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Wed, 13 Dec 2017 18:51:59 -0500 Subject: [PATCH 8/8] Removed comment about OData --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 61850d92f..3c1221d34 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,6 @@ The OpenAPI.NET project holds the base object model for representing OpenAPI des The base JSON and YAML Readers are built into this project. Below is the list of supported "reader" projects. - .NET Comment Reader: [Coming Soon] -- OData (CSDL) Reader: [Coming Soon] # Example Usage