Skip to content

Commit 683aed4

Browse files
authored
Merge pull request #2357 from martincostello/patch-1
docs: Improve upgrade guide formatting
2 parents f5d6e81 + a3adb2a commit 683aed4

File tree

1 file changed

+12
-12
lines changed

1 file changed

+12
-12
lines changed

docs/upgrade-guide-2.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -362,9 +362,9 @@ public class OpenApiSchema : IMetadataContainer, IOpenApiExtensible, IOpenApiRef
362362
There are a number of new features in OpenAPI v3.1 that are now supported in OpenAPI.NET.
363363

364364
### JsonSchema Dialect and BaseUri in OpenApiDocument
365-
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.
365+
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.
366366

367-
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.
367+
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.
368368

369369
```csharp
370370
/// <summary>
@@ -517,7 +517,7 @@ string json = document.SerializeAs(OpenApiSpecVersion.OpenApi3_0, OpenApiConstan
517517

518518
### Use OpenApiConstants string Instead of OpenApiFormat Enum
519519

520-
OpenApiConstants are now used instead of OpenApiFormat enums.
520+
`OpenApiConstants` are now used instead the `OpenApiFormat` enumeration.
521521

522522
**Example:**
523523

@@ -531,7 +531,7 @@ var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, Open
531531

532532
### OpenApiSchema's Type property is now a flaggable enum
533533

534-
In v2.0, the Type property in OpenApiSchema is now defined as a flaggable enum, allowing consumers to swap nullable for type arrays.
534+
In v2.0, the Type property in `OpenApiSchema` is now defined as a flaggable enum, allowing consumers to swap nullable for type arrays.
535535

536536
**Example:**
537537
```csharp
@@ -581,7 +581,7 @@ document.AddComponent<T>(string id, T componentToRegister);
581581
The following structural improvements have been made to the OpenAPI model layer to enhance type safety, extensibility, and maintainability:
582582

583583
1. Model Interfaces Introduced:
584-
Each model now has a corresponding interface (e.g., IOpenApiSchema for OpenApiSchema). This allows for better abstraction and testing support, while also simplifying cross-cutting concerns like serialization.
584+
Each model now has a corresponding interface (e.g., `IOpenApiSchema` for `OpenApiSchema`). This allows for better abstraction and testing support, while also simplifying cross-cutting concerns like serialization.
585585

586586
2. Models as Reference Types:
587587
All models are now implemented as reference types to ensure consistent identity semantics, especially when managing circular references or shared definitions.
@@ -590,13 +590,13 @@ All models are now implemented as reference types to ensure consistent identity
590590
A standardized pattern has been introduced for casting model instances to specific types safely and predictably, reducing the risk of invalid casts or reflection-based logic.
591591

592592
4. Removed Reference Fields from Base Models:
593-
Fields like Reference that were previously defined on base model types have been removed. Models that support referencing now handle this behavior explicitly via composition rather than inheritance.
593+
Properties like `Reference` that were previously defined on base model types have been removed. Models that support referencing now handle this behavior explicitly via composition rather than inheritance.
594594

595595
5. New Target and RecursiveTarget Properties:
596-
A Target property that points to the actual resolved model instance as well as a RecursiveTarget property that handles recursive references and supports advanced dereferencing logic have been introduced.
596+
A `Target` property that points to the actual resolved model instance as well as a `RecursiveTarget` property that handles recursive references and supports advanced dereferencing logic have been introduced.
597597

598598
6. Removed OpenApiReferenceResolver:
599-
This resolver class has been removed in favor of a more streamlined resolution model using the Target and RecursiveTarget properties along with updated reader/serializer pipelines.
599+
This resolver class has been removed in favor of a more streamlined resolution model using the `Target` and `RecursiveTarget` properties along with updated reader/serializer pipelines.
600600

601601
### Visitor and Validator now pass an interface model
602602

@@ -611,11 +611,11 @@ public override void Visit(IOpenApiParameter parameter){}
611611

612612
### Cleaned up the IEffective/GetEffective infrastructure
613613

614-
All the IEffective and GetEffective methods in the models have been removed as we've implemented lazy reference resolution using the proxy design.
614+
All the `IEffective` and `GetEffective` infrastructure in the models have been removed as we've implemented lazy reference resolution using the proxy design.
615615

616616
### Shallow Copy in place of copy constructors
617617

618-
Copy constructors for referenceable components have been made internal, a new *CreateShallowCopy()* method has been exposed on these models to facilitate cloning.
618+
Copy constructors for referenceable components have been made internal, a new `CreateShallowCopy()` method has been exposed on these models to facilitate cloning.
619619

620620
**Example:**
621621
```csharp
@@ -629,7 +629,7 @@ The redundant _style property on the Parameter model has been removed to simplif
629629

630630
### Discriminator now use References
631631

632-
Discriminator mappings have been updated from using a Dictionary<string, string> to a Dictionary<string, OpenApiSchemaReference>. This change improves the handling of discriminator mappings by referencing OpenAPI schema components more explicitly, which enhances schema resolution.
632+
Discriminator mappings have been updated from using a `Dictionary<string, string>` to a `Dictionary<string, OpenApiSchemaReference>`. This change improves the handling of discriminator mappings by referencing OpenAPI schema components more explicitly, which enhances schema resolution.
633633

634634
**Example:**
635635
```csharp
@@ -674,4 +674,4 @@ OpenApiSchemaReference schemaRef = new OpenApiSchemaReference("MySchema")
674674
## Feedback
675675

676676
If you have any feedback please file a GitHub issue [here](https://github.com/microsoft/OpenAPI.NET/issues)
677-
The team is looking forward to hear your experience trying the new version and we hope you have fun busting out your OpenAPI 3.1 descriptions.
677+
The team is looking forward to hear your experience trying the new version and we hope you have fun busting out your OpenAPI 3.1 descriptions.

0 commit comments

Comments
 (0)