Apib2swagger Save

Convert API Blueprint to Swagger 2.0 or OpenAPI 3.0.

Project README

apib2swagger

Build Status Coverage Status npm version

Convert API Blueprint to Swagger 2.0 or OpenAPI 3.0.

Supported versions:

  • API Blueprint 1A9
  • 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

Copyright (c) 2021 Keisuke Minami

MIT

Open Source Agenda is not affiliated with "Apib2swagger" Project. README Source: kminami/apib2swagger
Stars
198
Open Issues
12
Last Commit
5 months ago
License
MIT

Open Source Agenda Badge

Open Source Agenda Rating