API Blueprint to Swagger Converter

API Blueprint is simple and accessible to everybody involved in the API lifecycle. Its syntax is concise yet expressive. With API Blueprint you can quickly design and prototype APIs to be created or document and test already deployed mission-critical APIs. As an example, Apiary also uses API Blueprint.

We can convert API Blueprint to Swagger by using apib2swagger.

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

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

Use as a library.

var apib2swagger = require('apib2swagger'),
    apib = '...',
    options = { preferReference: true, bearerAsApikey: false };

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 kminami/apib2swagger -i /docs/api.md -o /docs/swagger.json

You can use container images in GitHub Container Registory like ghcr.io/kminami/apib2swagger or ghcr.io/kminami/apib2swagger:1.12.0 instead of Docker Hub.