Tomograph

Convert API Blueprint, Swagger and OpenAPI to minimal routes with JSON Schema. For ease of use and creation of new tools.

Will look like

```json
[
{
  "path": "/sessions",
  "method": "POST",
  "content-type": "application/json",
  "requests": [{
    "$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"
          }
        }
      }
    }
  ]
}
]
```

Installation

Then add this line to your application's Gemfile:

gem 'tomograph'

After that execute:

$ bundle

Or install the gem by yourself:

$ gem install tomograph

Usage

In code

OpenAPI 2.0

Also Swagger

require 'tomograph'

tomogram = Tomograph::Tomogram.new(openapi2_json_path: '/path/to/doc.json')

OpenAPI 3.0

Also OpenAPI

require 'tomograph'

tomogram = Tomograph::Tomogram.new(openapi3_yaml_path: '/path/to/doc.yaml')

API Blueprint

First you need to install drafter. Works after conversion from API Blueprint to API Elements (in YAML file) with Drafter.

That is, I mean that you first need to do this

drafter doc.apib -o doc.yaml

and then

require 'tomograph'

tomogram = Tomograph::Tomogram.new(drafter_yaml_path: '/path/to/doc.yaml')

Tomograph

To use additional features of the pre-converted

require 'tomograph'

tomogram = Tomograph::Tomogram.new(tomogram_json_path: '/path/to/doc.json')

prefix

Default: ''

You can specify API prefix and path to the spec using one of the possible formats:

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

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

to_json

Use to_json for converting to JSON, example from API Blueprint:

tomogram.to_json

Example input

```apib
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

```json
[
{
  "path": "/sessions",
  "method": "POST",
  "content-type": "application/json",
  "requests": [{
    "$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"
          }
        }
      }
    }
  ]
}
]
```

to_a

tomogram.to_a

find_request

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

find_request_with_content_type

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')

prefix_match?

This may be useful if you specify a prefix.

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

to_resources

Maps resources for API Blueprint with possible requests.

Example output:

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

Command line tool

CLI allows you to convert files from API Blueprint (API Elements), Swagger and OpenAPI to JSON Schema.

Run CLI with -h to get detailed help:

tomograph -h

To specify the handler version use the -d flag:

OpenAPI 2.0

tomograph -d openapi2 openapi2.json tomogram.json

OpenAPI 3.0

tomograph -d openapi3 openapi3.yaml doc.json

API Blueprint

tomograph -d 4 apielemetns.yaml doc.json

exclude-description

Exclude "description" keys from json-schemas.

tomograph -d 4 apielemetns.yaml doc.json --exclude-description

split

Split output into files by method. Output in dir path.

tomograph -d 4 --split apielemetns.yaml jsons/

License

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

Sponsored by FunBox