Epic: Support OpenApi 3

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: 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
  • 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 https://github.com/RSuter/NSwag/issues/1504

[themultiplexer]

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

Currently it is only 3.0.

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