Tomograph

Convert API Blueprint to JSON Schema and search.

Installation

First you need to install drafter.

Second add this line to your application's Gemfile:

gem 'tomograph'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tomograph

Usage

require 'tomograph'

tomogram = Tomograph::Tomogram.new(apib_path: '/path/to/doc.apib')

Command line tool

The command line tool allows you to convert files from API Blueprint or API Elements to JSON Schema.

tomograph doc.apib doc.json

Now there is support for documents pre-parsed by drafter versions 3 and 4, or crafter. To select the handler version, use the -d key and specify the required version. For example:

tomograph -d 4 doc_by_drafter4.yaml doc.json

See

tomograph -h

for more details on usage.

Convert

tomogram.to_json

Example input:

FORMAT: 1A
HOST: http://test.local

# project

# Group project

Project

## Authentication [/sessions]

### Sign In [POST]

+ Request (application/json)

    + Attributes
     + login (string, required)
     + password (string, required)
     + captcha (string, optional)

+ Response 401 (application/json)

+ Response 429 (application/json)

+ Response 201 (application/json)

    + Attributes
     + confirmation (Confirmation, optional)
     + captcha (string, optional)
     + captcha_does_not_match (boolean, optional)


# Data Structures

## Confirmation (object)
  + id (string, required)
  + type (string, required)
  + operation (string, required)

Example output:

[
  {
    "path": "/sessions",
    "method": "POST",
    "content-type": "application/json",
    "request": {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "type": "object",
      "properties": {
        "login": {
          "type": "string"
        },
        "password": {
          "type": "string"
        },
        "captcha": {
          "type": "string"
        }
      },
      "required": [
        "login",
        "password"
      ]
    },
    "responses": [
      {
        "status": "401",
        "content-type": "application/json",
        "body": {}
      },
      {
        "status": "429",
        "content-type": "application/json",
        "body": {}
      },
      {
        "status": "201",
        "content-type": "application/json",
        "body": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "properties": {
            "confirmation": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "operation": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "type",
                "operation"
              ]
            },
            "captcha": {
              "type": "string"
            },
            "captcha_does_not_match": {
              "type": "boolean"
            }
          }
        }
      }
    ]
  }
]

Search

find_request

request = tomogram.find_request(method: 'GET', path: '/status/1?qwe=rty')

find_request

request = tomogram.find_request_with_content_type(method: 'GET', path: '/status/1?qwe=rty', content_type: 'application/json')

find_responses

responses = request.find_responses(status: '200')

Other methods

prefix_match?

This can be useful if you use a prefix.

tomogram.prefix_match?('http://local/api/v2/users')

Params

Example:

Tomograph::Tomogram.new(prefix: '/api/v2', apib_path: '/path/to/doc.apib')

or

Tomograph::Tomogram.new(prefix: '/api/v2', drafter_yaml_path: '/path/to/doc.yaml')

or

Tomograph::Tomogram.new(prefix: '/api/v2', tomogram_json_path: '/path/to/doc.json')

apib_path

Path to API Blueprint documentation. There must be an installed drafter to parse it.

drafter_yaml_path

Path to API Blueprint documentation pre-parsed with drafter and saved to a YAML file.

Drafter v.4

If you are using a drafter v.4, then you need to use the following parametersdrafter_4_apib_path and drafter_4_yaml_path respectively.

Crafter

In case when you want to use сrafter, then you need to specify these parameters crafter_apib_path, crafter_yaml_path.

tomogram_json_path

Path to API Blueprint documentation converted with tomograph to a JSON file.

prefix

Default empty String. Prefix of API requests. Example: '/api'.

to_resources

Hash resource with requests. The result for the example above:

{
  '/sessions' => ['POST /sessions']
}

License

The gem is available as open source under the terms of the MIT License.