OpenAPI 3 support

The NSwag serializer supports Swagger 2.0 and OpenApi 3.0. This works by mapping all Swagger 2.0 properties to the OpenApi 3.0 properties. Depending on the serialization schema type (set in SwaggerDocument.FromJsonAsync() and ToJson()) some properties are ignored or serialized differently. The OpenApi 3.0 part of the model is the storage location and sync master if possible.

To enable OpenAPI 3.0.0 generation, choose one of these steps:

• Change the generator settings: settings.SchemaType = JsonSchemaType.OpenApi3;
• Change the ASP.NET Core service configuration: Add a document with AddOpenApiDocument() instead of AddSwaggerDocument(), see AspNetCore Middleware
• (Serialize a document to OpenAPI 3.0.0: document.ToJson(JsonSchemaType.OpenApi3), not recommended as it is not able to convert a document completely!!!)
  • Not recommended, change the output type in CLI: /outputType:OpenApi3
  • This feature might be removed because it might be too hard to maintain it

The version dependent properties: SwaggerDocument.Serialization.cs

Some sample Swagger 2.0 and OpenAPI 3.0 specifications can be compared here: https://github.com/RSuter/NSwag/tree/master/src/NSwag.Sample.NETCore20/Output

To update, just start the sample app and run Update-SwaggerSpecs.ps1.

Issues

• Epic tracking the OpenApi 3 support
• All open OpenApi 3 issues