LucyBot-Inc / api-spec-converter

Convert API descriptions between popular formats such as OpenAPI(fka Swagger), RAML, API Blueprint, WADL, etc.
https://lucybot-inc.github.io/api-spec-converter/
MIT License
1.11k stars 179 forks source link

openapi_3: Support for OpenAPI 3.1 #303

Open kevinoid opened 3 years ago

kevinoid commented 3 years ago

api-spec-converter 2.12.0 fails to convert an OpenAPI 3.1.0 document with the following error:

Fatal Error: Unsupported version
    at /path/to/api-spec-converter/lib/base_format.js:157:15
    at tryCatcher (/path/to/api-spec-converter/node_modules/bluebird/js/release/util.js:16:23)
    at Promise._settlePromiseFromHandler (/path/to/api-spec-converter/node_modules/bluebird/js/release/promise.js:512:31)
    at Promise._settlePromise (/path/to/api-spec-converter/node_modules/bluebird/js/release/promise.js:569:18)
    at Promise._settlePromise0 (/path/to/api-spec-converter/node_modules/bluebird/js/release/promise.js:614:10)
    at Promise._settlePromises (/path/to/api-spec-converter/node_modules/bluebird/js/release/promise.js:694:18)
    at _drainQueueStep (/path/to/api-spec-converter/node_modules/bluebird/js/release/async.js:138:12)
    at _drainQueue (/path/to/api-spec-converter/node_modules/bluebird/js/release/async.js:131:9)
    at Async._drainQueues (/path/to/api-spec-converter/node_modules/bluebird/js/release/async.js:147:5)
    at Immediate.Async.drainQueues [as _onImmediate] (/path/to/api-spec-converter/node_modules/bluebird/js/release/async.js:17:14)
    at processImmediate (internal/timers.js:461:21)

This occurs whether or not the document uses any features introduced in OpenAPI 3.1.0. For example, from the api-spec-converter repo:

sed 's/"openapi": "3\.0\.0"/"openapi": "3.1.0"/' test/input/openapi_3/minimal.json |
    ./bin/api-spec-converter --from openapi_3 --to swagger_2 /dev/fd/0

The immediate error can be fixed by adding '3.1' to OpenApi3.prototype.supportedVersions. However, I opened this issue to discuss whether there are any other "must have" features from OpenAPI 3.1.0 (to either support or explicitly reject), or if you'd accept a PR that just adds '3.1'.

Thanks for considering, Kevin

zacharypuulsedev commented 1 year ago

At least one difference exists in how OAS 3.1 handles nullability.

IIRC, OAS 3

type:  string
nullable: true

OAS 3.1

type: 
  - string
  - null