howyi/lamb

Generate API docs from JSON Schema

, _(*1)

lamb

JSON Schema(&YAML) extension & API document generator, _(*2)

Usable API

Quickstart

Install

composer require howyi/lamb, _(*3)

Config

Put lamb.yml in current working directory, _(*4)

name: LambTestAPI
version: 1.0.0

path:
  collection:  sample/collection
  environment: sample/environment
  request:     sample/request
  scenario:    sample/scenario

environment:
  host: https://example.com/v2

default:
  request:
    header:
      sessionKey:
        value: ((sessionKey))
    parameter:
      # sessionKey:
      #   required: true
      #   value: ((sessionKey))

API format

YAML

sample/collection/account/settings.yml
API endpoint: https://example.com/v2/account/settings, _(*5)

POST:
  description: Updates user's settings.

  request:
    body:
      $schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        language:
          title: user's language
          type: string
        age:
          title: age
          type: integer
      additionalProperties: true
      required: []


  response:
    body:
      $schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        language:
          title: user's language
          type: string
        age:
          title: age
          type: integer
      additionalProperties: true
      required: [language, age]

JSON

sample/collection/account/update_profile.json
API endpoint: https://example.com/v2/account/update_profile, _(*6)

{
  "POST": {

    "description": "Updates user's profile.",

    "request": {
      "body": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "type": "object",
        "properties": {
          "language": {
            "title": "user's language",
            "type": "string"
          },
          "age": {
            "title": "age",
            "type": "integer"
          }
        },
        "additionalProperties": true,
        "required" : []
      }
    },

    "response": {
      "body": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "type": "object",
        "properties": {
          "language": {
            "title": "user's language",
            "type": "string"
          },
          "age": {
            "title": "age",
            "type": "integer"
          }
        },
        "additionalProperties": true,
        "required" : ["language", "age"]
      }
    }

  }
}

Environment format

YAML

sample/environment/sample_env.yml, _(*7)

sessionKey: hogehogehogehoge

JSON

{
  "sessionKey": "hogehogehogehoge"
}

Generate POSTMAN Collection

$collection = \Lamb\CollectionStructureFactory::fromDir();
dump(\Lamb\Converter\Postman::collection($collection));

$environment = \Lamb\EnvironmentStructureFactory::fromDir();
dump(\Lamb\Converter\Postman::environment($environment));

Generate Swagger document

$collection = \Lamb\CollectionStructureFactory::fromDir();
$environment = \Lamb\EnvironmentStructureFactory::fromDir();

dump(\Lamb\Converter\Swagger::document($collection, $environment, 'your_env'));

Generate API Blueprint document

$collection = \Lamb\CollectionStructureFactory::fromDir();

dump(\Lamb\Converter\ApiBlueprint::document($collection));

Generate RAML document

$collection = \Lamb\CollectionStructureFactory::fromDir();
$environment = \Lamb\EnvironmentStructureFactory::fromDir();

dump(\Lamb\Converter\Raml::document($collection, $environment, 'your_env'));