Package Exports

apib2swagger
apib2swagger/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (apib2swagger) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

apib2swagger

Convert API Blueprint to Swagger 2.0 or OpenAPI 3.0.

Supported versions:

API Blueprint 1A9
- Metadata section
  - HOST -> .host, .basePath, .schemes
  - VERSION -> .info.version
- Include directive
Swagger 2.0
OpenAPI 3.0.3
Node.js 18.x, 20.x or higher

Install

$ npm install -g apib2swagger

Usage

Convert to Swagger specification.

$ apib2swagger -i api.md
$ apib2swagger -i api.md -o swagger.json
$ apib2swagger -i api.md --yaml -o swagger.yaml
$ apib2swagger -i api.md --prefer-reference
$ apib2swagger -i api.md --bearer-apikey
$ apib2swagger -i api.md --open-api-3
$ apib2swagger -i api.md --info-title "My API Document Title"
$ apib2swagger -i api.md --prefer-file-ref

Without -i option it reads from STDIN, without -o option writes to STDOUT.

$ apib2swagger < api.md > swagger.json
$ cat api.md | apib2swagger

Run http server with SwaggerUI. SwaggerUI will be automatically downloaded to current dir.

$ apib2swagger -i api.md -s
$ apib2swagger -i api.md -s -p 3000

# When using file references and running the SwaggerUI server, you can specify the source
# directory with the -sd flag. It will check the input directory and execution directory
# if -sd is not given.
$ apib2swagger -i api.md -s --prefer-file-ref -sd ~/project/src/

Use as a library.

var apib2swagger = require('apib2swagger'),
    apib = '...',
    options = { 
        preferReference: true, 

        // optional (Swagger 2.0 only).
        bearerAsApikey: false,

        // optional. swagger 2.0 is used by default.
        openApi3: true, 

        // optional. title will be grabbed from blueprint if not specified.
        infoTitle: 'My API Document Title', 

        // optional (Open API 3 only). 
        // will set a $ref to the given file path instead of including the file contents.
        preferFileRef: true 
    };

apib2swagger.convert(apib, options, function (error, result) {
    if (!error) console.log(result.swagger);
});

npx

You can run apib2swagger via npx (without first needing to install it) like so:

cat api.md | npx apib2swagger > swagger.json

Docker

You can also run apib2swagger inside a docker container.

$ docker run -it --rm -v $(pwd):/docs ghcr.io/kminami/apib2swagger -i /docs/api.md -o /docs/swagger.json

License

MIT