plan.md

Plan

Questions

OpenAPI 2.0 vs OpenAPI 3.0

Currently, almost all Azure OpenAPI specifications are OpenAPI 2.0. There is no official JSON-Schema for OpenAPI 3.0. See OAI/OpenAPI-Specification#1032.

Syntax

Current

{
    "swagger": "2.0",

    "paths": {
        "somepath/something": {
            "get": {
                "operationId": "someOperationId"
            }
        }
    }
}

Proposed

{
    "swagger": "2.0",
    "discriminator": "api-version",
    "paths": {
        "somepath/something": {
            "get": [
                {
                    "operationId": "someOperationId",
                    "parameters": {
                        "api-version": { "enum": ["2013-05", "2013-06"] }
                    }
                },
                {
                    "operationId": "someOperationId",
                    "parameters": {
                        "api-version": { "enum": ["2013-06"] }
                    }
                }
            ]
        }
    }
}

See also JSON-Schema. Enumerated Values.

Questions

1. Discriminator should have all values

   "discriminator": {
       "name": "api-version",
       "enum": ["2013-05", "2013-06"]
   }

2. Should we rename Operations to OperationOverload?

Presentation Feedback

1. GitHub project url
   1. accepting proposals/feedbacks
2. operation example
   1. a webpage which can show generated files. Interactive?
3. Vision/RoadMap for features