Epic: Support OpenApi 3

[RicoSuter]

Documentation in the wiki

Specification:

• https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md
• https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

Changes:

• https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

Tasks:

• Step 1: Support v2 and v3 models in NSwag.Core
  • [x] Implement all new contracts in the existing model classes (SwaggerDocument)
    • See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#openapi-object
  • [x] Support null and oneOf => null is not supported but a new property "nullable" :-(
  • [x] Conditionally serialize either one of the two versions (i.e. ignore or rename properties)
    • [ ] e.g. ToJson() with an additional enum parameter SchemaType (Swagger2 | OpenApi3)
  • [x] Support "nullable": Add bool? IsNullableRaw to JsonSchema4 (default: false)
  • [x] Support new discriminator format: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminator-object
  • [x] Implement OpenApiMediaType.Encoding
• Step 2: Swagger generators
  • [x] Optionally generate Swagger 2.x or OpenAPI 3.x specs in the Swagger generators (Web API)
  • [ ] Support new array parameters and properties: https://github.com/RSuter/NSwag/issues/1091
  • [ ] Generate deepObject: https://github.com/RSuter/NSwag/issues/1594
• Step 3: Code generators
  • [ ] Generate code based on the new models (should support both versions), i.e. only use OpenAPI 3 properties (which are set by the Swagger 2.0 properties) and do not use Swagger 2.0 properties anymore. Then support new OpenAPI 3.0 properties/features without breaking old and Swagger 2.0 features.
  • [ ] Support wildcard http status codes: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responses-object

Open questions:

• OpenApiRequestBody
  • [x] How to handle nullable body objects? Schema with nullable=true and allOf reference?
• SwaggerResponse
  • [x] How to handle nullable responses? With schema.nullable and allOf reference?
• Serialization
  • [ ] Correctly support serializing to 2.0 or 3.0, see https://github.com/RSuter/NSwag/issues/1504

[stijnherreman]

Is it possible to help you with this? I'm particularly interested in the new (or improved?) multipart support described in the spec, it'll allow adding API methods that take multipart/mixed content.

[RicoSuter]

Hi @stijnherreman, yes, I'd really appreciate it!

I think the first step is to find a way to enhance the model (NSwag.Core) so that both versions (2/3) can be serialized/deserialized from a single set of model classes (see updated issue). There are properties which have to be renamed or ignored depending on the spec version - for this we have a custom contract resolver (see https://blog.rsuter.com/advanced-newtonsoft-json-dynamically-rename-or-ignore-properties-without-changing-the-serialized-class/).

I'm not sure yet, how we can maintain both versions in a single set of model classes (inheritance, only ignore/rename properties, property prefix?).

I think we should start with the simpler thinks, like the new server specification (these are just new properties on SwaggerDocument, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject). Then we can look into the new response handling, schema changes, etc...

[daniel-gwilt-software]

https://github.com/RSuter/NSwag/issues/1091

[RicoSuter]

Most recent commits for enhancing the model for OpenApi 3:

https://github.com/RSuter/NSwag/commit/3e22a080e439741b4105d8f5c32a6430507abf4e https://github.com/RSuter/NSwag/commit/1eebd6a978d8a02cf861cffe189d4c7b4954350a https://github.com/RSuter/NSwag/commit/8dfa231cd5d9b80e20f53f03a16c3c7df56106bd https://github.com/RSuter/NSwag/commit/aa3d161550232c4b23ba98f39e22ffda3923eb00 https://github.com/RSuter/NSwag/commit/ef1d3d185d832e16206ade0bde068629e72b9efd

[RicoSuter]

Most unit tests for the OpenApi 3 serialization are here: https://github.com/RSuter/NSwag/tree/master/src/NSwag.Core.Tests/Serialization

If someone (@stijnherreman ?) wants to help, we need more unit tests, some OpenApi 3 properties are still missing, etc...

The main idea is to add all properties from Swagger and OpenApi and then based on the target, ignore/hide or rename some properties. The Swagger properties which have an OpenApi equivalent should just be derived properties and update/read the OpenApi properties when being accessed... (see SwaggerDocument.Serialization.cs - there are also the renames/ignores)

[RicoSuter]

The specs can be found here:

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

most properties of OpenApi are implemented, what currently is missing (and which are the hardest one to sync):

• Operation.requestBody: Operation.parameters.bodyParameter (Swagger) should sync with Operation.requestBody (OpenApi) (hard to implement with change tracking etc.)
• Response.content: Response.schema (Swagger) should sync with Response.content (OpenApi) (easier to implement)

[RicoSuter]

For proper inheritance support we also need:

• https://github.com/RSuter/NJsonSchema/issues/224 (swagger generator)
• https://github.com/RSuter/NJsonSchema/issues/13 (code generator)

[RicoSuter]

Ref https://github.com/RSuter/NSwag/commit/ea63ef29b0acf580791bf4f1e089adc13e617849

[stijnherreman]

Due to priority changes in our project I won't be able to spend time on this for now, unfortunately. Perhaps in a couple months, if help is still needed.

[RicoSuter]

@stijnherreman I then, I think help will also be needed in a couple of months :-)

[RicoSuter]

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.

[RicoSuter]

PR to add explode and parameter style: https://github.com/RSuter/NSwag/pull/1342

[themultiplexer]

I guess a very small adjustment needs to be done to the open-api version number:

Currently it is only 3.0.

[foscjos2]

I notice that this epic is still open and has some uncompleted tasks - is OAPI 3.0 fully supported in this library?

[rshettybr]

Is this usable to upgrade to Open API 3 standard.