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
Copy file name to clipboardExpand all lines: docs/upgrade-guide-2.md
+12-12Lines changed: 12 additions & 12 deletions
Original file line number
Diff line number
Diff line change
@@ -362,9 +362,9 @@ public class OpenApiSchema : IMetadataContainer, IOpenApiExtensible, IOpenApiRef
362
362
There are a number of new features in OpenAPI v3.1 that are now supported in OpenAPI.NET.
363
363
364
364
### 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.
366
366
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.
### Use OpenApiConstants string Instead of OpenApiFormat Enum
519
519
520
-
OpenApiConstants are now used instead of OpenApiFormat enums.
520
+
`OpenApiConstants` are now used instead the `OpenApiFormat` enumeration.
521
521
522
522
**Example:**
523
523
@@ -531,7 +531,7 @@ var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, Open
531
531
532
532
### OpenApiSchema's Type property is now a flaggable enum
533
533
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.
535
535
536
536
**Example:**
537
537
```csharp
@@ -581,7 +581,7 @@ document.AddComponent<T>(string id, T componentToRegister);
581
581
The following structural improvements have been made to the OpenAPI model layer to enhance type safety, extensibility, and maintainability:
582
582
583
583
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.
585
585
586
586
2. Models as Reference Types:
587
587
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
590
590
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.
591
591
592
592
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.
594
594
595
595
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.
597
597
598
598
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.
600
600
601
601
### Visitor and Validator now pass an interface model
602
602
@@ -611,11 +611,11 @@ public override void Visit(IOpenApiParameter parameter){}
611
611
612
612
### Cleaned up the IEffective/GetEffective infrastructure
613
613
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.
615
615
616
616
### Shallow Copy in place of copy constructors
617
617
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.
619
619
620
620
**Example:**
621
621
```csharp
@@ -629,7 +629,7 @@ The redundant _style property on the Parameter model has been removed to simplif
629
629
630
630
### Discriminator now use References
631
631
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.
633
633
634
634
**Example:**
635
635
```csharp
@@ -674,4 +674,4 @@ OpenApiSchemaReference schemaRef = new OpenApiSchemaReference("MySchema")
674
674
## Feedback
675
675
676
676
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