You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In OpenAPI v1, it was necessary to include the Microsoft.OpenApi.Readers library to be able to read OpenAPI descriptions in either YAML or JSON. In OpenAPI.NET v2, the core Microsoft.OpenAPI library can both read and write JSON. It is only necessary to use the newly renamed [Microsoft.OpenApi.YamlReader](https://www.nuget.org/packages/Microsoft.OpenApi.YamlReader/) library if you need YAML support. This allows teams who are only working in JSON to avoid the additional dependency and therefore eliminate all non-.NET library references.
101
+
In OpenAPI v1, it was necessary to include the Microsoft.OpenApi.Readers library to be able to read OpenAPI descriptions in either YAML or JSON. In OpenAPI.NET v2, the core Microsoft.OpenAPI library can both read and write JSON. It is only necessary to use the newly renamed [Microsoft.OpenApi.YamlReader](https://www.nuget.org/packages/Microsoft.OpenApi.YamlReader/) library if you need YAML support. This allows teams who are only working in JSON to avoid the additional dependency and therefore eliminate all non-.NET library references.
102
102
103
103
Once the dependency is added, the reader needs to be added to the reader settings as demonstrated below
The same pattern can be used for `OpenApiStreamReader` and `OpenApiTextReader`. When we introduced the `ReadAsync` methods we eliminated the use of the `out` parameter. To improve code readability, we've added deconstruction support to `ReadResult`. The properties also have been renamed to avoid confusion with their types.
123
+
The same pattern can be used for `OpenApiStreamReader` and `OpenApiTextReader`. When we introduced the `ReadAsync` methods we eliminated the use of the `out` parameter. To improve code readability, we've added deconstruction support to `ReadResult`. The properties also have been renamed to avoid confusion with their types.
124
124
125
125
```csharp
126
126
varreader=newOpenApiStreamReader();
@@ -146,11 +146,11 @@ public class OpenApiDocument {
146
146
}
147
147
```
148
148
149
-
This API design allows a developer to use IDE autocomplete to present all the loading options by simply knowing the name of the `OpenApiDocument` class. Each of these methods are layered on top of the more primitive methods to ensure consistent behavior.
149
+
This API design allows a developer to use IDE autocomplete to present all the loading options by simply knowing the name of the `OpenApiDocument` class. Each of these methods are layered on top of the more primitive methods to ensure consistent behavior.
150
150
151
-
As the YAML format is only supported when including the `Microsoft.OpenApi.YamlReader` library it was decided not to use an enum for the `format` parameter. We are considering implementing a more [strongly typed solution](https://github.com/microsoft/OpenAPI.NET/issues/1952) similar to the way that `HttpMethod` is implemented so that we have a strongly typed experience that is also extensible.
151
+
As the YAML format is only supported when including the `Microsoft.OpenApi.YamlReader` library it was decided not to use an enum for the `format` parameter. We are considering implementing a more [strongly typed solution](https://github.com/microsoft/OpenAPI.NET/issues/1952) similar to the way that `HttpMethod` is implemented so that we have a strongly typed experience that is also extensible.
152
152
153
-
When the loading methods are used without a format parameter, we will attempt to parse the document using the default JSON reader. If that fails and the YAML reader is registered, then we will attempt to read as YAML. The goal is always to provide the fastest path with JSON but still maintain the convenience of not having to care whether a URL points to YAML or JSON if you need that flexibility.
153
+
When the loading methods are used without a format parameter, we will attempt to parse the document using the default JSON reader. If that fails and the YAML reader is registered, then we will attempt to read as YAML. The goal is always to provide the fastest path with JSON but still maintain the convenience of not having to care whether a URL points to YAML or JSON if you need that flexibility.
154
154
155
155
### Additional exceptions
156
156
@@ -284,7 +284,7 @@ var info = schema.Metadata["foo"];
284
284
285
285
### Updates to OpenApiSchema
286
286
287
-
The OpenAPI 3.1 specification changes significantly how it leverages JSON Schema. In 3.0 and earlier, OpenAPI used a "subset, superset" of JSON Schema draft-4. This caused many problems for developers trying to use JSON Schema validation libraries with the JSON Schema in their OpenAPI descriptions. In OpenAPI 3.1, the 2020-12 draft version of JSON Schema was adopted and a new JSON Schema vocabulary was adopted to support OpenAPI specific keywords. All attempts to constrain what JSON Schema keywords could be used in OpenAPI were removed.
287
+
The OpenAPI 3.1 specification changes significantly how it leverages JSON Schema. In 3.0 and earlier, OpenAPI used a "subset, superset" of JSON Schema draft-4. This caused many problems for developers trying to use JSON Schema validation libraries with the JSON Schema in their OpenAPI descriptions. In OpenAPI 3.1, the 2020-12 draft version of JSON Schema was adopted and a new JSON Schema vocabulary was adopted to support OpenAPI specific keywords. All attempts to constrain what JSON Schema keywords could be used in OpenAPI were removed.
288
288
289
289
#### New keywords introduced in 2020-12
290
290
@@ -311,24 +311,24 @@ public bool UnevaluatedProperties { get; set;}
311
311
#### Changes to existing keywords
312
312
313
313
```csharp
314
-
publicstring?ExclusiveMaximum { get; set; } // type changed to reflect the new version of JSON schema
314
+
publicstring?ExclusiveMaximum { get; set; } // type changed to reflect the new version of JSON schema
315
315
publicstring?ExclusiveMinimum { get; set; } // type changed to reflect the new version of JSON schema
316
-
publicJsonSchemaType?Type { get; set; } // Was string, now flagged enum
316
+
publicJsonSchemaType?Type { get; set; } // Was string, now flagged enum
317
317
publicstring?Maximum { get; set; } // type changed to overcome double vs decimal issues
318
318
publicstring?Minimum { get; set; } // type changed to overcome double vs decimal issues
319
319
320
-
publicJsonNodeDefault { get; set; } // Type matching no longer enforced. Was IOpenApiAny
321
-
publicboolReadOnly { get; set; } // No longer has defined semantics in OpenAPI 3.1
322
-
publicboolWriteOnly { get; set; } // No longer has defined semantics in OpenAPI 3.1
320
+
publicJsonNodeDefault { get; set; } // Type matching no longer enforced. Was IOpenApiAny
321
+
publicboolReadOnly { get; set; } // No longer has defined semantics in OpenAPI 3.1
322
+
publicboolWriteOnly { get; set; } // No longer has defined semantics in OpenAPI 3.1
323
323
324
-
publicJsonNodeExample { get; set; } // No longer IOpenApiAny
324
+
publicJsonNodeExample { get; set; } // No longer IOpenApiAny
publicIDictionary<string, object>Metadata { get; set; } // Custom property bag to be used by the application, used to be named annotations
331
+
publicIDictionary<string, object>Metadata { get; set; } // Custom property bag to be used by the application, used to be named annotations
332
332
```
333
333
334
334
#### OpenApiSchema methods
@@ -353,7 +353,7 @@ There are a number of new features in OpenAPI v3.1 that are now supported in Ope
353
353
354
354
### JsonSchema Dialect and BaseUri in OpenApiDocument
355
355
356
-
To enable full compatibility with JSON Schema, the `OpenApiDocument` class now supports a `JsonSchemaDialect` property. This property specifies the JSON Schema dialect used throughout the document, using a URI. By explicitly declaring the dialect, tooling can be directed to use a JSON Schema version other than the default [2020-12 draft](https://json-schema.org/draft/2020-12/json-schema-core.html). However, OpenAPI.NET does not guarantee compatibility with versions other than 2020-12.
356
+
To enable full compatibility with JSON Schema, the `OpenApiDocument` class now supports a `JsonSchemaDialect` property. This property specifies the JSON Schema dialect used throughout the document, using a URI. By explicitly declaring the dialect, tooling can be directed to use a JSON Schema version other than the default [2020-12 draft](https://json-schema.org/draft/2020-12/json-schema-core.html). However, OpenAPI.NET does not guarantee compatibility with versions other than 2020-12.
357
357
358
358
In addition, a `BaseUri` property has been added to represent the identity of the OpenAPI document. If the document’s identity is not provided or cannot be determined at based on its location, this property will be set to a generated placeholder URI.
359
359
@@ -379,7 +379,7 @@ public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IMetada
0 commit comments