doca/example/product.json

A CLI tool that scaffolds API documentation based on JSON HyperSchemas.

{
  "id": "/product",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Product",
  "description": "A product available for sale in a store",
  "type": "object",
  "definitions": {
    "identifier": {
      "type": "string",
      "description": "Product SKU",
      "example": "ABC-123"
    },
    "name": {
      "type": "string",
      "description": "Product's name",
      "maxLength": 100
    },
    "description": {
      "type": "string",
      "description": "Product's description",
      "maxLength": 2000
    },
    "price": {
      "type": "number",
      "description": "The price of the product",
      "example": 49.99
    },
    "currency": {
      "enum": ["USD"],
      "description": "The currency of the price"
    },
    "in_stock": {
      "type": "boolean",
      "description": "Whether the product is in stock or not",
      "example": true,
      "default": false
    },
    "available_qty": {
      "type": "number",
      "description": "The quantity of the product available for purchasing",
      "example": 10,
      "default": 0
    },
    "image": {
      "type": "string",
      "description": "URL for the product image",
      "example": "http://static.example.com/images/product.jpg"
    }
  },
  "required": [
    "ID",
    "name",
    "description",
    "price",
    "currency",
    "in_stock",
    "available_qty"
  ],
  "properties": {
    "ID": {"$ref": "#/definitions/identifier"},
    "name": {"$ref": "#/definitions/name"},
    "description": {"$ref": "#/definitions/description"},
    "price": {"$ref": "#/definitions/price"},
    "currency": {"$ref": "#/definitions/currency"},
    "in_stock": {"$ref": "#/definitions/in_stock"},
    "available_qty": {"$ref": "#/definitions/available_qty"},
    "image": {"$ref": "#/definitions/image"}
  },
  "additionalProperties": {
    "image_gallery": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/image"
      }
    }
  },
  "links": [
    {
      "title": "Available products",
      "description": "Get all available product for the store",
      "rel": "instances",
      "href": "/products",
      "method": "GET",
      "schema": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "description": "Current page of products",
            "example": 1,
            "default": 1
          },
          "per_page": {
            "type": "integer",
            "description": "How many products to retrieve at once",
            "min": 1,
            "max": 200,
            "default": 20
          },
          "order": {
            "enum": ["name", "price", "available_qty"],
            "description": "Attribute to order the results by",
            "example": "price"
          }
        }
      },
      "targetSchema": {
        "type": "object",
        "properties": {
          "products": {
            "type": "array",
            "items": {"rel": "self"}
          }
        }
      }
    },{
      "title": "Product info",
      "description": "Get a single product",
      "rel": "self",
      "href": "/products/{#/definitions/identifier}",
      "method": "GET",
      "targetSchema": {"rel": "self"}
    }
  ]
}