Skip to content

Commit 0b45f60

Browse files
authored
Fix some more white space
1 parent c7a58f0 commit 0b45f60

File tree

1 file changed

+19
-19
lines changed

1 file changed

+19
-19
lines changed

docs/upgrade-guide-2.md

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -98,13 +98,13 @@ mySchema.AnyOf = new List<IOpenApiSchema> { otherSchema };
9898

9999
## Reduced Dependencies
100100

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.
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.
102102

103103
Once the dependency is added, the reader needs to be added to the reader settings as demonstrated below
104104

105105
```csharp
106106
var settings = new OpenApiReaderSettings();
107-
settings.AddYamlReader();
107+
settings.AddYamlReader();
108108

109109
var result = OpenApiDocument.LoadAsync(openApiString, settings: settings);
110110
```
@@ -120,7 +120,7 @@ var reader = new OpenApiStringReader();
120120
var openApiDoc = reader.Read(stringOpenApiDoc, out var diagnostic);
121121
```
122122

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.
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.
124124

125125
```csharp
126126
var reader = new OpenApiStreamReader();
@@ -146,11 +146,11 @@ public class OpenApiDocument {
146146
}
147147
```
148148

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.
150150

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.
152152

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.
154154

155155
### Additional exceptions
156156

@@ -284,7 +284,7 @@ var info = schema.Metadata["foo"];
284284

285285
### Updates to OpenApiSchema
286286

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.
288288

289289
#### New keywords introduced in 2020-12
290290

@@ -311,24 +311,24 @@ public bool UnevaluatedProperties { get; set;}
311311
#### Changes to existing keywords
312312

313313
```csharp
314-
public string? ExclusiveMaximum { get; set; } // type changed to reflect the new version of JSON schema
314+
public string? ExclusiveMaximum { get; set; } // type changed to reflect the new version of JSON schema
315315
public string? ExclusiveMinimum { get; set; } // type changed to reflect the new version of JSON schema
316-
public JsonSchemaType? Type { get; set; } // Was string, now flagged enum
316+
public JsonSchemaType? Type { get; set; } // Was string, now flagged enum
317317
public string? Maximum { get; set; } // type changed to overcome double vs decimal issues
318318
public string? Minimum { get; set; } // type changed to overcome double vs decimal issues
319319
320-
public JsonNode Default { get; set; } // Type matching no longer enforced. Was IOpenApiAny
321-
public bool ReadOnly { get; set; } // No longer has defined semantics in OpenAPI 3.1
322-
public bool WriteOnly { get; set; } // No longer has defined semantics in OpenAPI 3.1
320+
public JsonNode Default { get; set; } // Type matching no longer enforced. Was IOpenApiAny
321+
public bool ReadOnly { get; set; } // No longer has defined semantics in OpenAPI 3.1
322+
public bool WriteOnly { get; set; } // No longer has defined semantics in OpenAPI 3.1
323323
324-
public JsonNode Example { get; set; } // No longer IOpenApiAny
324+
public JsonNode Example { get; set; } // No longer IOpenApiAny
325325
public IList<JsonNode> Examples { get; set; }
326326
public IList<JsonNode> Enum { get; set; }
327-
public OpenApiExternalDocs ExternalDocs { get; set; } // OpenApi Vocab
328-
public bool Deprecated { get; set; } // OpenApi Vocab
329-
public OpenApiXml Xml { get; set; } // OpenApi Vocab
327+
public OpenApiExternalDocs ExternalDocs { get; set; } // OpenApi Vocab
328+
public bool Deprecated { get; set; } // OpenApi Vocab
329+
public OpenApiXml Xml { get; set; } // OpenApi Vocab
330330
331-
public IDictionary<string, object> Metadata { get; set; } // Custom property bag to be used by the application, used to be named annotations
331+
public IDictionary<string, object> Metadata { get; set; } // Custom property bag to be used by the application, used to be named annotations
332332
```
333333

334334
#### OpenApiSchema methods
@@ -353,7 +353,7 @@ There are a number of new features in OpenAPI v3.1 that are now supported in Ope
353353

354354
### JsonSchema Dialect and BaseUri in OpenApiDocument
355355

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.
357357

358358
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.
359359

@@ -379,7 +379,7 @@ public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IMetada
379379

380380
```csharp
381381

382-
public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IOpenApiMetadataContainer
382+
public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IOpenApiMetadataContainer
383383
{
384384
public IDictionary<string, OpenApiPathItem>? Webhooks { get; set; } = new Dictionary<string, OpenApiPathItem>();
385385
}

0 commit comments

Comments
 (0)