apib2json

A command-line utility to convert API Blueprint to JSON Schema.

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 there is the task: Convert Blueprint to JSON Schema. This tool is specially for it.

It is built on top of apiaryio/protagonist which do hard job, but if you know this Node.js C++ binding you sure know that compilation of this library (npm install protagonist) takes time. 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: Recommended way is using a dockerized version, just try $ docker run --rm bugyik/apib2json --help

Usage

$ apib2json --help

Usage: apib2json [options]

A command-line utility to convert API Blueprint to JSON Schema

Options:

    -h, --help           output usage information
    -V, --version        output the version number
    -v, --verbose        Verbose mode, use with --output - default: false
    -p, --pretty         Output pretty (indented) JSON - default: false
    --indent <n>         Number of space characters used to indent code, use with --pretty - default: 2
    -i, --input <file>   Path to input (Apib) file - default: STDIN
    -o, --output <file>  Path to output (JSON) file - default: STDOUT

Example

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

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

$ cat input.apib

## 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": null
      },
      "schema": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "created": {
            "type": "number",
            "description": "Time stamp"
          },
          "percent_off": {
            "type": "number",
            "description": "A positive integer between 1 and 100 that represents the discount the coupon will apply."
          },
          "redeem_by": {
            "type": "number",
            "description": "Date after which the coupon can no longer be redeemed"
          }
        },
        "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!

Do you hate contributing to projects where you have to install direct version of Node.js? I know there are tools like nvm but there is also Docker to rescue! To begin developing, you just need docker and docker-compose installed and do this:

$ git clone git@github.com:o5/apib2json.git && cd apib2json/
$ docker-compose up

Do you need to go inside the container?

$ docker exec -it apib2json sh

NOTE: Assumes docker-composer up was finished.

License

MIT @ Petr Bugyík