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
  • 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
  • Support null and oneOf => null is not supported but a new property "nullable" :-(
  • 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)
  • Support "nullable": Add bool? IsNullableRaw to JsonSchema4 (default: false)
  • Support new discriminator format: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminator-object
  • Implement OpenApiMediaType.Encoding
• Step 2: Swagger generators
  • Optionally generate Swagger 2.x or OpenAPI 3.x specs in the Swagger generators (Web API)
  • Support new array parameters and properties: Support OAS 3 - Operation Parameter Serialization for Complex Objects #1091
  • Generate deepObject: OpenAPI 3: Generate deepObject for complex query parameter #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
  • How to handle nullable body objects? Schema with nullable=true and allOf reference?
• SwaggerResponse
  • How to handle nullable responses? With schema.nullable and allOf reference?
• Serialization
  • Correctly support serializing to 2.0 or 3.0, see Correctly handle parameter.schema in ToJson() instead of generator #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]

#1091

[RicoSuter]

Most recent commits for enhancing the model for OpenApi 3:

3e22a08
1eebd6a
8dfa231
aa3d161
ef1d3d1

[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:

• Failing Validation: Inheritance NJsonSchema#224 (swagger generator)
• Support oneOf inheritance for code generators NJsonSchema#13 (code generator)

[RicoSuter]

Ref ea63ef2

[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: #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.