Skip to content

Commit 7a3f93f

Browse files
baywetbaywet
authored
Merge pull request #2409 from microsoft/release-please--branches--main--components--Microsoft.OpenApi
chore(main): release 2.0.0-preview.30
2 parents 0bea5ed + 938e351 commit 7a3f93f

File tree

4 files changed

+157
-145
lines changed

4 files changed

+157
-145
lines changed

‎.release-please-manifest.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
".": "2.0.0-preview.29"
2+
".": "2.0.0-preview.30"
33
}

‎CHANGELOG.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,17 @@
11
# Changelog
22

3+
## [2.0.0-preview.30](https://github.com/microsoft/OpenAPI.NET/compare/v2.0.0-preview.29...v2.0.0-preview.30) (2025-07-02)
4+
5+
6+
### Bug Fixes
7+
8+
* migration of hidi to the latest version of system.commandline ([a5f8721](https://github.com/microsoft/OpenAPI.NET/commit/a5f8721a18e93ee881cfee371ba6d23ce0c55ae4))
9+
* throw on circular reference ([e14258d](https://github.com/microsoft/OpenAPI.NET/commit/e14258dd2a8639702c8e0bc81a643874d207facb))
10+
* throw on circular reference ([caea292](https://github.com/microsoft/OpenAPI.NET/commit/caea292b39d2c754bd2e2d214280add53a0a47ea))
11+
* upgrades openapi.odata to avoid hidi failing to load ([0bea5ed](https://github.com/microsoft/OpenAPI.NET/commit/0bea5ed3cbb10230bf026288e118ce0e5025e55a))
12+
* upgrades openapi.odata to avoid hidi failing to load ([6735397](https://github.com/microsoft/OpenAPI.NET/commit/67353976b8a17dcb6760223d06c097469fa6f794))
13+
* validation to accept lowercase status code ranges (4xx, 5xx) in OpenAPI responses ([09f661f](https://github.com/microsoft/OpenAPI.NET/commit/09f661f0ff0511d5937fad49ae8a6182b1ea1aff))
14+
315
## [2.0.0-preview.29](https://github.com/microsoft/OpenAPI.NET/compare/v2.0.0-preview.28...v2.0.0-preview.29) (2025-06-18)
416

517

‎Directory.Build.props

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
<PackageProjectUrl>https://github.com/Microsoft/OpenAPI.NET</PackageProjectUrl>
1313
<Copyright>© Microsoft Corporation. All rights reserved.</Copyright>
1414
<PackageTags>OpenAPI .NET</PackageTags>
15-
<Version>2.0.0-preview.29</Version>
15+
<Version>2.0.0-preview.30</Version>
1616
</PropertyGroup>
1717
<!-- https://github.com/clairernovotny/DeterministicBuilds#deterministic-builds -->
1818
<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">

‎README.md

Lines changed: 143 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,143 @@
1-
<!-- using the raw image URL so it displays correctly on nuget.org -->
2-
![Category overview screenshot](https://raw.githubusercontent.com/microsoft/OpenAPI.NET/main/docs/images/oainet.png "Microsoft + OpenAPI = Love")
3-
4-
# OpenAPI.NET
5-
6-
|Package|Nuget|
7-
|--|--|
8-
|Models and Writers|[![nuget](https://img.shields.io/nuget/v/Microsoft.OpenApi.svg)](https://www.nuget.org/packages/Microsoft.OpenApi/) |
9-
|Readers | [![nuget](https://img.shields.io/nuget/v/Microsoft.OpenApi.Readers.svg)](https://www.nuget.org/packages/Microsoft.OpenApi.Readers/) |
10-
|Hidi|[![nuget](https://img.shields.io/nuget/v/Microsoft.OpenApi.Hidi.svg)](https://www.nuget.org/packages/Microsoft.OpenApi.Hidi/)
11-
12-
13-
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.
14-
15-
**See more information on the OpenAPI specification and its history here: <a href="https://www.openapis.org">OpenAPI Initiative</a>**
16-
17-
Project Objectives:
18-
19-
- Provide a single shared object model in .NET for OpenAPI descriptions.
20-
- Include the most primitive Reader for ingesting OpenAPI JSON and YAML documents in both V2 and V3 formats.
21-
- Provide OpenAPI description writers for both V2 and V3 specification formats.
22-
- Enable developers to create Readers that translate different data formats into OpenAPI descriptions.
23-
24-
# Installation
25-
26-
- Install core Nuget package [**Microsoft.OpenApi**](https://www.nuget.org/packages/Microsoft.OpenApi)
27-
- Install readers Nuget package [**Microsoft.OpenApi.Readers**](https://www.nuget.org/packages/Microsoft.OpenApi.Readers)
28-
29-
> Note: version 2 of this library, which brings support for OpenAPI 3.1, is currently in preview. Due to early versioning issues with the preview, and package renaming, the installation must be done with a specific version number to get the latest version:
30-
> ```bash
31-
> # x-release-please-start-version
32-
> dotnet add package Microsoft.OpenAPI --version 2.0.0-preview.29
33-
> # x-release-please-end
34-
> # x-release-please-start-version
35-
> dotnet add package Microsoft.OpenAPI.YamlReader --version 2.0.0-preview.29
36-
> # x-release-please-end
37-
> ```
38-
> Until this new version is generally available, dependabot will periodically create pull requests which **downgrade** to preview 9, they should be ignored.
39-
> You can read more about the changes of this upcoming version [in the upgrade guide](./docs/upgrade-guide-2.md).
40-
41-
# Processors
42-
The OpenAPI.NET project holds the base object model for representing OpenAPI documents as .NET objects. Some developers have found the need to write processors that convert other data formats into this OpenAPI.NET object model. We'd like to curate that list of processors in this section of the readme.
43-
44-
The base JSON and YAML processors are built into this project. Below is the list of the other supported processor projects.
45-
46-
- [**C# Comment / Annotation Processor**](https://github.com/Microsoft/OpenAPI.NET.CSharpAnnotations) : Converts standard .NET annotations ( /// comments ) emitted from your build (MSBuild.exe) into OpenAPI.NET document object.
47-
48-
- [**OData CSDL Processor**](https://github.com/Microsoft/OpenAPI.NET.OData) : Converts the XML representation of the Entity Data Model (EDM) describing an OData Service into OpenAPI.NET document object.
49-
50-
# Example Usage
51-
52-
Creating an OpenAPI Document
53-
54-
```C#
55-
var document = new OpenApiDocument
56-
{
57-
Info = new OpenApiInfo
58-
{
59-
Version = "1.0.0",
60-
Title = "Swagger Petstore (Simple)",
61-
},
62-
Servers = new List<OpenApiServer>
63-
{
64-
new OpenApiServer { Url = "http://petstore.swagger.io/api" }
65-
},
66-
Paths = new OpenApiPaths
67-
{
68-
["/pets"] = new OpenApiPathItem
69-
{
70-
Operations = new()
71-
{
72-
[HttpMethod.Get] = new OpenApiOperation
73-
{
74-
Description = "Returns all pets from the system that the user has access to",
75-
Responses = new OpenApiResponses
76-
{
77-
["200"] = new OpenApiResponse
78-
{
79-
Description = "OK"
80-
}
81-
}
82-
}
83-
}
84-
}
85-
}
86-
};
87-
```
88-
89-
Reading and writing an OpenAPI description
90-
91-
```C#
92-
var httpClient = new HttpClient
93-
{
94-
BaseAddress = new Uri("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/")
95-
};
96-
97-
var stream = await httpClient.GetStreamAsync("main/examples/v3.0/petstore.yaml");
98-
99-
// Read V3 as YAML
100-
var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostic);
101-
102-
// Write V2 as JSON
103-
var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json);
104-
105-
```
106-
107-
# Validating/Testing OpenAPI descriptions
108-
In order to test the validity of an OpenApi document, we avail the following tools:
109-
- [Microsoft.OpenApi.Hidi](https://www.nuget.org/packages/Microsoft.OpenApi.Hidi)
110-
111-
A commandline tool for validating and transforming OpenAPI descriptions. [Installation guidelines and documentation](https://github.com/microsoft/OpenAPI.NET/blob/main/src/Microsoft.OpenApi.Hidi/readme.md)
112-
113-
- Microsoft.OpenApi.Workbench
114-
115-
A workbench tool consisting of a GUI where you can test and convert OpenAPI descriptions in both JSON and YAML from v2-->v3 and vice versa.
116-
117-
#### Installation guidelines:
118-
1. Clone the repo locally by running this command:
119-
`git clone https://github.com/microsoft/OpenAPI.NET.git`
120-
2. Open the solution file `(.sln)` in the root of the project with Visual Studio
121-
3. Navigate to the `src/Microsoft.OpenApi.Workbench` directory and set it as the startup project
122-
4. Run the project and you'll see a GUI pop up resembling the one below:
123-
124-
125-
![workbench preview](https://raw.githubusercontent.com/microsoft/OpenAPI.NET/main/docs/images/workbench.png "a screenshot of the workbench application")
126-
127-
5. Copy and paste your OpenAPI descriptions in the **Input Content** window or paste the path to the descriptions file in the **Input File** textbox and click on `Convert` to render the results.
128-
129-
# Contributing
130-
131-
This project welcomes contributions and suggestions. Most contributions require you to agree to a
132-
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
133-
the rights to use your contribution. For details, visit https://cla.microsoft.com.
134-
135-
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
136-
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
137-
provided by the bot. You will only need to do this once across all repos using our CLA.
138-
139-
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
140-
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
141-
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
142-
143-
To provide feedback and ask questions you can use Stack Overflow with the [OpenAPI.NET](https://stackoverflow.com/questions/tagged/openapi.net) tag.
1+
<!-- using the raw image URL so it displays correctly on nuget.org -->
2+
![Category overview screenshot](https://raw.githubusercontent.com/microsoft/OpenAPI.NET/main/docs/images/oainet.png "Microsoft + OpenAPI = Love")
3+
4+
# OpenAPI.NET
5+
6+
|Package|Nuget|
7+
|--|--|
8+
|Models and Writers|[![nuget](https://img.shields.io/nuget/v/Microsoft.OpenApi.svg)](https://www.nuget.org/packages/Microsoft.OpenApi/) |
9+
|Readers | [![nuget](https://img.shields.io/nuget/v/Microsoft.OpenApi.Readers.svg)](https://www.nuget.org/packages/Microsoft.OpenApi.Readers/) |
10+
|Hidi|[![nuget](https://img.shields.io/nuget/v/Microsoft.OpenApi.Hidi.svg)](https://www.nuget.org/packages/Microsoft.OpenApi.Hidi/)
11+
12+
13+
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.
14+
15+
**See more information on the OpenAPI specification and its history here: <a href="https://www.openapis.org">OpenAPI Initiative</a>**
16+
17+
Project Objectives:
18+
19+
- Provide a single shared object model in .NET for OpenAPI descriptions.
20+
- Include the most primitive Reader for ingesting OpenAPI JSON and YAML documents in both V2 and V3 formats.
21+
- Provide OpenAPI description writers for both V2 and V3 specification formats.
22+
- Enable developers to create Readers that translate different data formats into OpenAPI descriptions.
23+
24+
# Installation
25+
26+
- Install core Nuget package [**Microsoft.OpenApi**](https://www.nuget.org/packages/Microsoft.OpenApi)
27+
- Install readers Nuget package [**Microsoft.OpenApi.Readers**](https://www.nuget.org/packages/Microsoft.OpenApi.Readers)
28+
29+
> Note: version 2 of this library, which brings support for OpenAPI 3.1, is currently in preview. Due to early versioning issues with the preview, and package renaming, the installation must be done with a specific version number to get the latest version:
30+
> ```bash
31+
> # x-release-please-start-version
32+
> dotnet add package Microsoft.OpenAPI --version 2.0.0-preview.30
33+
> # x-release-please-end
34+
> # x-release-please-start-version
35+
> dotnet add package Microsoft.OpenAPI.YamlReader --version 2.0.0-preview.30
36+
> # x-release-please-end
37+
> ```
38+
> Until this new version is generally available, dependabot will periodically create pull requests which **downgrade** to preview 9, they should be ignored.
39+
> You can read more about the changes of this upcoming version [in the upgrade guide](./docs/upgrade-guide-2.md).
40+
41+
# Processors
42+
The OpenAPI.NET project holds the base object model for representing OpenAPI documents as .NET objects. Some developers have found the need to write processors that convert other data formats into this OpenAPI.NET object model. We'd like to curate that list of processors in this section of the readme.
43+
44+
The base JSON and YAML processors are built into this project. Below is the list of the other supported processor projects.
45+
46+
- [**C# Comment / Annotation Processor**](https://github.com/Microsoft/OpenAPI.NET.CSharpAnnotations) : Converts standard .NET annotations ( /// comments ) emitted from your build (MSBuild.exe) into OpenAPI.NET document object.
47+
48+
- [**OData CSDL Processor**](https://github.com/Microsoft/OpenAPI.NET.OData) : Converts the XML representation of the Entity Data Model (EDM) describing an OData Service into OpenAPI.NET document object.
49+
50+
# Example Usage
51+
52+
Creating an OpenAPI Document
53+
54+
```C#
55+
var document = new OpenApiDocument
56+
{
57+
Info = new OpenApiInfo
58+
{
59+
Version = "1.0.0",
60+
Title = "Swagger Petstore (Simple)",
61+
},
62+
Servers = new List<OpenApiServer>
63+
{
64+
new OpenApiServer { Url = "http://petstore.swagger.io/api" }
65+
},
66+
Paths = new OpenApiPaths
67+
{
68+
["/pets"] = new OpenApiPathItem
69+
{
70+
Operations = new()
71+
{
72+
[HttpMethod.Get] = new OpenApiOperation
73+
{
74+
Description = "Returns all pets from the system that the user has access to",
75+
Responses = new OpenApiResponses
76+
{
77+
["200"] = new OpenApiResponse
78+
{
79+
Description = "OK"
80+
}
81+
}
82+
}
83+
}
84+
}
85+
}
86+
};
87+
```
88+
89+
Reading and writing an OpenAPI description
90+
91+
```C#
92+
var httpClient = new HttpClient
93+
{
94+
BaseAddress = new Uri("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/")
95+
};
96+
97+
var stream = await httpClient.GetStreamAsync("main/examples/v3.0/petstore.yaml");
98+
99+
// Read V3 as YAML
100+
var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostic);
101+
102+
// Write V2 as JSON
103+
var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json);
104+
105+
```
106+
107+
# Validating/Testing OpenAPI descriptions
108+
In order to test the validity of an OpenApi document, we avail the following tools:
109+
- [Microsoft.OpenApi.Hidi](https://www.nuget.org/packages/Microsoft.OpenApi.Hidi)
110+
111+
A commandline tool for validating and transforming OpenAPI descriptions. [Installation guidelines and documentation](https://github.com/microsoft/OpenAPI.NET/blob/main/src/Microsoft.OpenApi.Hidi/readme.md)
112+
113+
- Microsoft.OpenApi.Workbench
114+
115+
A workbench tool consisting of a GUI where you can test and convert OpenAPI descriptions in both JSON and YAML from v2-->v3 and vice versa.
116+
117+
#### Installation guidelines:
118+
1. Clone the repo locally by running this command:
119+
`git clone https://github.com/microsoft/OpenAPI.NET.git`
120+
2. Open the solution file `(.sln)` in the root of the project with Visual Studio
121+
3. Navigate to the `src/Microsoft.OpenApi.Workbench` directory and set it as the startup project
122+
4. Run the project and you'll see a GUI pop up resembling the one below:
123+
124+
125+
![workbench preview](https://raw.githubusercontent.com/microsoft/OpenAPI.NET/main/docs/images/workbench.png "a screenshot of the workbench application")
126+
127+
5. Copy and paste your OpenAPI descriptions in the **Input Content** window or paste the path to the descriptions file in the **Input File** textbox and click on `Convert` to render the results.
128+
129+
# Contributing
130+
131+
This project welcomes contributions and suggestions. Most contributions require you to agree to a
132+
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
133+
the rights to use your contribution. For details, visit https://cla.microsoft.com.
134+
135+
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
136+
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
137+
provided by the bot. You will only need to do this once across all repos using our CLA.
138+
139+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
140+
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
141+
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
142+
143+
To provide feedback and ask questions you can use Stack Overflow with the [OpenAPI.NET](https://stackoverflow.com/questions/tagged/openapi.net) tag.

0 commit comments

Comments
 (0)