# apib2swagger

> Convert API Blueprint to Swagger.

Latest version **1.17.1** (published 2023-10-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install apib2swagger
pnpm add apib2swagger
yarn add apib2swagger
bun add apib2swagger
```

Provides the command `apib2swagger`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.17.1 |
| Published | 2023-10-22 |
| First published | 2015-02-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 8 |
| Unpacked size | 545.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 209 |
| Author | Keisuke Minami |
| Maintainers | kminami |

## Links

- npm: https://www.npmjs.com/package/apib2swagger
- Repository: https://github.com/kminami/apib2swagger
- Homepage: https://github.com/kminami/apib2swagger#readme
- Issues: https://github.com/kminami/apib2swagger/issues
- npm.io page: https://npm.io/package/apib2swagger

## Dependencies (8)

- [nopt](https://npm.io/package/nopt.md) ^3.0.6
- [js-yaml](https://npm.io/package/js-yaml.md) ^4.1.0
- [drafter.js](https://npm.io/package/drafter.js.md) ^2.6.2
- [uritemplate](https://npm.io/package/uritemplate.md) ^0.3.4
- [lodash.isequal](https://npm.io/package/lodash.isequal.md) ^4.5.0
- [generate-schema](https://npm.io/package/generate-schema.md) ^2.5.0
- [apib-include-directive](https://npm.io/package/apib-include-directive.md) ^0.1.0
- [json-schema-to-openapi-schema](https://npm.io/package/json-schema-to-openapi-schema.md) ^0.4.0

## Recent versions

- 1.17.1 (latest) — 2023-10-22
- 1.17.0 — 2023-10-21
- 1.16.1 — 2023-01-29
- 1.15.0 — 2022-05-17
- 1.14.3 — 2022-05-16
- 1.14.2 — 2022-03-24
- 1.14.1 — 2022-03-02
- 1.14.0 — 2021-12-25
- 1.13.0 — 2021-12-04
- 1.12.0 — 2020-09-12
- 1.11.0 — 2019-12-30
- 1.10.0 — 2019-06-22
- 1.9.2 — 2019-04-30
- 1.9.1 — 2019-04-30
- 1.9.0 — 2019-04-19
- … 27 more at https://npm.io/package/apib2swagger/versions

## README

# apib2swagger

![Build Status](https://github.com/kminami/apib2swagger/actions/workflows/nodejs.yml/badge.svg)
[![Coverage Status](https://coveralls.io/repos/github/kminami/apib2swagger/badge.svg?branch=master)](https://coveralls.io/github/kminami/apib2swagger?branch=master)
[![npm version](https://badge.fury.io/js/apib2swagger.svg)](https://badge.fury.io/js/apib2swagger)

Convert [API Blueprint](https://apiblueprint.org/) to [Swagger 2.0](http://swagger.io/) or [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification).

Supported versions:
- API Blueprint 1A9
    - [Metadata section](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-metadata-section)
        - HOST -> .host, .basePath, .schemes
        - VERSION -> .info.version
    - [Include directive](https://github.com/danielgtaylor/aglio#including-files)
- 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.
```shell
$ 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.
```shell
$ apib2swagger < api.md > swagger.json
$ cat api.md | apib2swagger
```

Run http server with SwaggerUI.
SwaggerUI will be automatically downloaded to current dir.
```shell
$ 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.
```javascript
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.

```bash
$ 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

---
_Source: https://npm.io/package/apib2swagger · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._