apib2json

A command-line utility for get JSON Schema(s) from API Blueprint.

Introduction

If you are building your API with Apiary you should know API Blueprint, right? Good documentation is cool but it would be nice to re-use your validation which you already wrote in MSON (or JSON Schema). So here is the task: Get JSON Schema(s) from API Blueprint. Good news for you: This tool does it!

It is built on top of apiaryio/protagonist which does the hard job, but if you know this Node.js C++ binding you sure know that compilation of this library (npm install protagonist) is very slow. This is the reason why this tool is also wrapped with Docker, but sure you can also use it with npm.

Installation

$ npm install --global apib2json

NOTE: The dockerized version is recommended, just try $ docker run --rm slimapi/apib2json --help

Usage

$ apib2json --help

Usage: apib2json [options]

A command-line utility for get JSON Schema(s) from API Blueprint

Options:
  -d, --debug          Debug (verbose) mode, use only with --output (default: false)
  -h, --help           Prints this help
  -i, --input <file>   Path to input (API Blueprint) file (default: STDIN)
  --indent <number>    Number of space characters used to indent code, use with --pretty (default: 2)
  -o, --output <file>  Path to output (JSON) file (default: STDOUT)
  -p, --pretty         Output pretty (indented) JSON (default: false)
  -v, --version        Prints version

Example

NOTE: The example below requires docker installed (npm's version without prefix docker run --rm -i slimapi/)

$ docker run --rm -i slimapi/apib2json --pretty < input.apib > output.json

$ cat input.apib

# Awesome API

## Coupon [/coupons/{id}]
A coupon contains information about a percent-off or amount-off discount you
might want to apply to a customer.

+ Attributes (object)
    + id: 250FF (string, required)
    + created: 1415203908 (number) - Time stamp
    + percent_off: 25 (number)

        A positive integer between 1 and 100 that represents the discount the coupon will apply.

    + redeem_by (number) - Date after which the coupon can no longer be redeemed

### Retrieve a Coupon [GET]
Retrieves the coupon with the given ID.

+ Response 200 (application/json)
    + Attributes (Coupon)

$ cat output.json

{
  "[GET]/coupons/{id}": [
    {
      "meta": {
        "type": "response",
        "title": "Retrieve a Coupon",
        "group": "Coupon",
        "statusCode": "200"
      },
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "created": {
            "type": "number"
          },
          "percent_off": {
            "type": "number"
          },
          "redeem_by": {
            "type": "number"
          }
        },
        "required": [
          "id"
        ]
      }
    }
  ]
}

NOTE: More examples of input/ouput are available in test/fixtures folder.

Contributing

Bug Reports & Feature Requests

Please use the issue tracker to report any bugs or file feature requests.

Developing

Pull Requests are welcome! To begin developing, you just need docker installed and do this:

$ git clone [e-mail]:slimapi/apib2json.git && cd apib2json/
$ docker compose up

Getting Into a Docker Container’s Shell

$ docker exec -it apib2json sh

Please run Lint & Test (inside of Docker Container)

$ npm run ci

License

MIT @ Petr Bugyík