Example swagger for bureaucrat integration

swagger.json

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Simple API",
    "description": "A Simple API.",
    "termsOfService": "Use at your own risk!",
    "contact": {
      "name": "Joe P. Coder"
    },
    "license": {
      "name": "All rights reserved."
    }
  },
  "host": "localhost:8080",
  "basePath": "/api/v1",
  "schemes": [
    "http"
  ],
  "consumes": [
    "application/vnd.api+json"
  ],
  "produces": [
    "application/vnd.api+json"
  ],
  "securityDefinitions" : {
    "basic_auth" : {
      "type": "basic",
      "description": "Standard HTTP basic authentication applies to all API operations."
    }
  },
  "security": {
    "basic_auth" : []
  },
  "tags": [
    {
      "name": "users",
      "description": "Operations related to users"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "tags": ["users"],
        "summary": "Query for users.",
        "description": "Query for users, supporting pagination and filtering by organization ID.",
        "operationId": "Api.V1.UserController.index",
        "produces": [
          "application/vnd.api+json"
        ],
        "parameters": [
          {
            "type": "integer",
            "required": false,
            "name": "page[size]",
            "in": "query",
            "description": "Page size",
            "default": 10,
            "x-example": "100"
          },
          {
            "type": "integer",
            "required": false,
            "name": "page[number]",
            "in": "query",
            "description": "Page Number",
            "default" : 1,
            "x-example": "7"
          },
          {
            "type": "string",
            "required": false,
            "name": "filter[organization_uuid]",
            "in": "query",
            "description": "Organization UUID",
            "x-example": "1234-123124-12213"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of users.",
            "schema": {
              "$ref": "#/definitions/Users"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Users": {
      "type": "object",
      "description": "A page of [User](#user) results",
      "properties": {
        "meta": {
          "type": "object",
          "properties": {
            "total-pages": {
              "type": "integer",
              "description" : "The total number of pages available"
            }
          },
          "required": [
            "total-pages"
          ]
        },
        "links": {
          "type": "object",
          "properties": {
            "self": {
              "type": "string",
              "description": "Link to this page of results"
            },
            "prev": {
              "type": "string",
              "description": "Link to the previous page of results"
            },
            "next": {
              "type": "string",
              "description": "Link to the next page of results"
            },
            "last": {
              "type": "string",
              "description": "Link to the last page of results"
            },
            "first": {
              "type": "string",
              "description": "Link to the first page of results"
            }
          },
          "required": [
            "self",
            "prev",
            "next",
            "last",
            "first"
          ]
        },
        "data": {
          "type": "array",
          "description": "Content with [User](#user) objects",
          "items": {
            "$ref": "#/definitions/User"
          }
        }
      },
      "required": [
        "meta",
        "links",
        "data"
      ],
      "example": {
        "meta": {
          "total-pages": 1
        },
        "links": {
          "self": "http://localhost:4001/api/v1/users?page[number]=1&page[size]=1",
          "prev": "",
          "next": "",
          "last": "http://localhost:4001/api/v1/users?page[number]=1&page[size]=1",
          "first": "http://localhost:4001/api/v1/users?page[number]=1&page[size]=1"
        },
        "data": [
          {
            "type": "users",
            "id": "2841943X",
            "attributes": {
              "user_updated_at": "",
              "user_created_at": "",
              "street_address": "I am a street address",
              "postal_code": "12345",
              "phone": "1800-IAMATEST",
              "full_name": "Aliza Schiller",
              "email": "[email protected]",
              "country": "Country",
              "birthday": ""
            }
          }
        ]
      }
    },
    "User": {
      "type": "object",
      "description": "A user of the application.",
      "properties": {
        "type": {
          "type": "string",
          "description": "This entity type, always \"user\""
        },
        "id": {
          "type": "string",
          "description": "The user unique ID"
        },
        "attributes": {
          "type": "object",
          "properties": {
            "user_updated_at": {
              "type": "string",
              "description": "Last update timestamp UTC"
            },
            "user_created_at": {
              "type": "string",
              "description": "First created timestamp UTC"
            },
            "street_address": {
              "type": "string",
              "description": "Street address"
            },
            "postal_code": {
              "type": "string",
              "description": "The users postal / zip code"
            },
            "phone": {
              "type": "string",
              "description" : "Users phone number"
            },
            "full_name": {
              "type": "string",
              "description" : "Full name"
            },
            "email": {
              "type": "string",
              "description" : "Email"
            },
            "country": {
              "type": "string",
              "description": "Country"
            },
            "birthday": {
              "type": "string",
              "description" : "Birthday in YYYY-MM-DD format"
            }
          },
          "required": [
            "user_updated_at",
            "user_created_at",
            "street_address",
            "postal_code",
            "phone",
            "full_name",
            "email",
            "country",
            "birthday"
          ]
        }
      },
      "required": [
        "type",
        "id",
        "attributes"
      ],
      "example": {
        "type": "user",
        "id": "99775670",
        "attributes": {
          "user_updated_at": "2016-05-28T23:11:45Z",
          "user_created_at": "2016-05-29T23:54:25Z",
          "street_address": "I am a street address",
          "postal_code": "12345",
          "phone": "1800-IAMATEST",
          "full_name": "Junius Batz",
          "email": "[email protected]",
          "country": "Country",
          "birthday": "1980-09-12"
        }
      }
    }
  }
}