Repository files navigation

This fork of the apib2swagger library is being done as a stopgap to enable someinternal tooling while we determine how to transition to native OpenAPIdocumentation.

There were some slight issues we noticed with the output of the mainlibrary, it has not been updated for a while (2 years at time of writing ofthis comment), and the api blueprint project itself has been archived.So it seemed more expeditious to just make a fork for our quick fixes.

At the moment, we have not added our org CI/CD tooling to make this forkedversion more widely available vianpm.

As such, if you need to use this version of apib2swagger instead of the standardnpm-provided one, the current process is to runnpm ci thennpm pack in thisrepo locally and then take the generatedtgz file, copy it over to the repoyou need to use it in, and runnpm i <path-to-local-tgz-file>.

If there's sufficient demand to make this version more widely available withinthe org, we can add the tooling to make it installable by standard means; butfor now it's meant to be used temporarily in one place for internal tools.

What follows is the documentation for the main apib2swagger library. If you haveany questions, please reach out to the systems-engineering team.

ConvertAPI Blueprint toSwagger 2.0 orOpenAPI 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

npm install -g apib2swagger

Convert to Swagger specification.

apib2swagger -i api.mdapib2swagger -i api.md -o swagger.jsonapib2swagger -i api.md --yaml -o swagger.yamlapib2swagger -i api.md --prefer-referenceapib2swagger -i api.md --bearer-apikeyapib2swagger -i api.md --open-api-3apib2swagger -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.jsoncat 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.

varapib2swagger=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);});

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

cat api.md| npx apib2swagger> swagger.json

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

Copyright (c) 2021 Keisuke Minami

MIT