slimapi / apib2json Goto Github PK

View Code? Open in Web Editor NEW

19.0 2.0 14.0 126 KB

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

License: MIT License

JavaScript 97.56% Dockerfile 2.44%

json-schema api-blueprint mson apib api validation

apib2json's Introduction

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 [email protected]: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

apib2json's People

Contributors

Stargazers

Watchers

Forkers

reactual rainawlk passiverecords mariochavez renesugar jean ahsandar armor josesaribeiro jay-coditas smujaddid memoxmrdl virtual360-io darkmatus

apib2json's Issues

Race condition

Hi,

I have found a bug but I'm not sure how to fix it. I have a document that includes a title for a response, parsing the file with apib2json does not return the title in meta object. Looking at the code, this line has the test to decide if the title should be set or not https://github.com/o5/apib2json/blob/master/lib/apib2json.js#L114

if ('meta' in httpTransaction && 'title' in httpTransaction.meta) {
    item.meta.title = httpTransaction.meta.title;
}

The issue is that httpTransaction.meta is empty at this point, inside the closure httpTransaction.content.forEach((rContent) => {}

But if I print httpTransaction.meta just before entering the closure the value is there.

Sorry, I'm not really a nodejs developer, I know for sure is a race condition but not sure how to fix it, I hope you can help me with this.

Cheers,
Mario

TypeError: Cannot read property 'contentType' of undefined

I tried to run apib2json on the following Blueprint: https://airdcpp.docs.apiary.io. I get the following error:

/src/apib2json/lib/apib2json.js:92
                                        if (isAsset && rContent.attributes.contentType === 'application/schema+json') {
                                                                           ^

TypeError: Cannot read property 'contentType' of undefined
    at httpTransaction.content.forEach (/src/apib2json/lib/apib2json.js:92:76)
    at Array.forEach (<anonymous>)
    at content.content.forEach (/src/apib2json/lib/apib2json.js:90:61)
    at Array.forEach (<anonymous>)
    at transition.content.forEach (/src/apib2json/lib/apib2json.js:72:49)
    at Array.forEach (<anonymous>)
    at resource.content.forEach (/src/apib2json/lib/apib2json.js:66:48)
    at Array.forEach (<anonymous>)
    at group.content.forEach (/src/apib2json/lib/apib2json.js:61:42)
    at Array.forEach (<anonymous>)

I did some debugging and there seems to be two resources that are missing the attributes key:

It seems to be when the response code is anything other than 2xx.

Did not recognizance contenttype

I tried using this tool to convert our blueprint to json and got a empty object as output.

After some debugging found out that line 93 of lib/apib2json.js was the problem.

It checks the content type for "application/scheme+json" While for the blueprint we use it was "application/json".

A possible solution for this is to check for both or make a regex expression to catch multiple cases (i have personally never seen scheme+json so there might be a few others i have never seen).

(For the rest this tool was exactly what i was looking for. No other npm module could give me something to mock requests that where defined in apib)

Missing atrribute in schema

Hi,

I have problem with parsing attributes and I do not know if I missing something or if this is a bug.

I will try to demonstrate it on following minimal example. This is the minimal blueprint file:

FORMAT: 1A

# Minimal example API

Example of minimal API

# Group Authentication

## Authentication [/et/v1/{id}/auth]
Authentication...

+ Parameters
    + id: `42` (number) - example id

### Initialize Authentication [GET]

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

# Data Structures

## BaseModel (object)
+ _links (string)

## AuthenticationModel (BaseModel)
+ example (boolean)

And this is corresponding json output, generated using apib2json.

{
  "[GET]/et/v1/{id}/auth": [
    {
      "meta": {
        "type": "response",
        "title": null,
        "group": "Authentication",
        "statusCode": "200"
      },
      "schema": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "type": "object",
        "properties": {
          "_links": {
            "type": "string"
          },
          "example": {
            "type": "boolean"
          }
        }
      }
    }
  ]
}

Unfortunately, I cannot find any information about id parameter in generated JSON file. Am I missing something or is it a bug?

File <input> cannot be opened

I keep getting File <input> cannot be opened any idea what could be the causes for this. I can generate HTML using snowboard from the apib file and and also checked for any error all looks good.

https://github.com/o5/apib2json/blob/44b0559a6d3ca4d9143ae068695f1291f5d88015/bin/apib2json#L61

Node 10 and greater support?

Is there a plan to support this module further? Currently due to the dependency on protagonist this tool is not useable in CIs running with Node LTS 10 and above. If protagonist is to remain a hard dependency either this module needs updating protagonist or decoupling from it. If there is no plan to support further versions of node then we should include a engine restriction in the package.json to prevent installs and throw an error when node version is greater than the supported version.

Remove docker instances after exiting

Hi, you should advise in the README to run the Docker image with --rm option, otherwise users will end up with tons of unused stale containers.

From docker run -h

      --rm                             Automatically remove the container when it exits