api-spec-converter adapted to 4th platform Swagger

Convert between API description formats such as Swagger and RAML

Currently only supports conversion to OpenAPI(fka Swagger) 2.0 format, and from OpenAPI 2.0 to OpenAPI 3.0.x

Conversion to OpenAPI 2.0 (Swagger) from OpenAPI 3.0 is done with several considerations to make it compatible with 4th platform swagger guidelines.

Installation

Command Line

npm i -g .

Docker

npm i -g .

Usage

Command Line

$ api-spec-converter -h

  Usage: api-spec-converter [options] <URL|filename>

  Convert API descriptions between popular formats.

  Supported formats:
    * swagger_1
    * swagger_2
    * openapi_3
    * api_blueprint
    * io_docs
    * google
    * raml
    * wadl

  Options:

    -h, --help              output usage information
    -V, --version           output the version number
    -f, --from <format>     Specifies format to convert
    -t, --to <format>       Specifies output format
    -s, --syntax [syntax]   Specifies output data syntax: json or yaml. Defaults to json
    -o, --order [sortOrder] Specifies top fields ordering: openapi or alpha. Defaults to openapi
    -c, --check             Check if result is valid spec
    -d, --dummy             Fill missing required fields with dummy data

Example:

$ api-spec-converter --from=openapi_3 --to=swagger_2 http://localhost:8080/docs/swagger/ > swagger.json

Supported Formats

• Swagger 1.x (swagger_1)
• OpenAPI(fka Swagger) 2.0 (swagger_2)
• OpenAPI 3.0.x (openapi_3)
• I/O Docs (io_docs)
• API Blueprint (api_blueprint)
• Google API Discovery (google)
• RAML (raml)
• WADL (wadl)

Conversion Table

from:	swagger_1	swagger_2	openapi_3	io_docs	api_blueprint	google	raml	wadl
to swagger_1	n/a
to swagger_2	✅	n/a	✅	✅	✅	✅	✅	✅
to openapi_3	✳️	✅	n/a	✳️	✳️	✳️	✳️	✳️
to io_docs				n/a
to api_blueprint					n/a
to google						n/a
to raml							n/a
to wadl								n/a

Key

• ✅ - direct conversion
• ✳️ - conversion via swagger_2

Contributing

Contributions are welcome and encouraged.

Testing

Please add a test case if you're adding features or fixing bugs. To run the tests:

npm test

In case you need to override the expected outputs, due to a justified and verified change, run this:

WRITE_GOLDEN=true npm test

Releases

docker build . -t agenthaac.azurecr.io/api-spec-converter:$VERSION
docker push agenthaac.azurecr.io/api-spec-converter:$VERSION