Self-describing Swagger YAML

swagger.json

{
    "swagger": "2.0",
    "info": {
        "description": "info.description",
        "version": "info.version",
        "title": "info.title",
        "termsOfService": "info.termsOfService",
        "contact": {
            "name": "info.contact.name",
            "url": "info.contact.url",
            "email": "info.contact.email@example.com"
        },
        "license": {
            "name": "info.license.name",
            "url": "info.license.url"
        }
    },
    "host": "host.com",
    "basePath": "/basePath",
    "schemes": [
        "http"
    ],
    "paths": {
        "/path": {
            "post": {
                "tags": [
                    "operation.tags"
                ],
                "summary": "operation.summary",
                "description": "operation.description",
                "operationId": "operation.operationId",
                "consumes": [
                    "operation.consumes"
                ],
                "produces": [
                    "operation.produces"
                ],
                "parameters": [
                    {
                        "in": "body",
                        "name": "body",
                        "description": "operation.parameters.description for body",
                        "required": false,
                        "schema": {
                            "$ref": "#/definitions/Definition"
                        }
                    },
                    {
                        "in": "header",
                        "name": "header",
                        "description": "operation.parameters.description for header",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "405": {
                        "description": "operation.responses.description"
                    }
                },
                "security": [
                    {
                        "security": [
                            "scope"
                        ]
                    }
                ]
            },
            "get": {
                "tags": [
                    "operation.tag"
                ],
                "summary": "operation.summary",
                "description": "operation.description",
                "operationId": "operation.operationId2",
                "consumes": [
                    "operation.consumes"
                ],
                "parameters": [
                    {
                        "in": "query",
                        "type": "string",
                        "name": "operation.parameters.query",
                        "description": "operation.parameters.description for query",
                        "required": false
                    }
                ],
                "responses": {
                    "200": {
                        "description": "operation.responses.description",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/Definition"
                            }
                        }
                    },
                    "400": {
                        "description": "operation.responses.description in-line"
                    }
                },
                "security": [
                    {
                        "security": [
                            "scope"
                        ]
                    }
                ]
            }
        }
    },
    "securityDefinitions": {
        "security": {
            "type": "oauth2",
            "authorizationUrl": "http://petstore.swagger.wordnik.com/api/oauth/dialog",
            "flow": "implicit",
            "scopes": {
                "scope": "securityDefinitions.name.scopes.name"
            }
        }
    },
    "definitions": {
        "Definition": {
            "properties": {
                "id": {
                    "type": "integer",
                    "format": "int64"
                },
                "username": {
                    "type": "string"
                },
                "firstName": {
                    "type": "string"
                },
                "lastName": {
                    "type": "string"
                },
                "email": {
                    "type": "string"
                },
                "password": {
                    "type": "string"
                },
                "phone": {
                    "type": "string"
                },
                "userStatus": {
                    "type": "integer",
                    "format": "int32",
                    "description": "User Status"
                }
            }
        }
    }
}

swagger.yaml

swagger: "2.0"
info:
  description: info.description
  version: "info.version"
  title: info.title
  termsOfService: info.termsOfService
  contact:
    name: info.contact.name
    url: info.contact.url
    email: info.contact.email@example.com
  license:
    name: info.license.name
    url: info.license.url
host: host.com
basePath: /basePath
schemes:
  - http
paths:
  /path:
    post:
      tags:
        - operation.tags
      summary: operation.summary
      description: operation.description
      operationId: operation.operationId
      consumes:
        - operation.consumes
      produces:
        - operation.produces
      parameters:
        - in: body
          name: body
          description: operation.parameters.description for body
          required: false
          schema:
            $ref: "#/definitions/Definition"
        - in: header
          name: header
          description: operation.parameters.description for header
          required: true
          type: string
      responses:
        "405":
          description: operation.responses.description
      security:
        - security:
          - scope
    get:
      tags:
        - operation.tag
      summary: operation.summary
      description: operation.description
      operationId: operation.operationId2
      consumes:
        - operation.consumes
      parameters:
        - in: query
          type: string
          name: operation.parameters.query
          description: operation.parameters.description for query
          required: false
      responses:
        "200":
          description: operation.responses.description
          schema:
            type: array
            items:
              $ref: "#/definitions/Definition"
        "400":
          description: operation.responses.description in-line
      security:
        - security:
          - scope
securityDefinitions:
  security: 
    type: oauth2
    authorizationUrl: http://petstore.swagger.wordnik.com/api/oauth/dialog
    flow: implicit
    scopes:
      scope: securityDefinitions.name.scopes.name
definitions:
  Definition:
    properties:
      id:
        type: integer
        format: int64
      username:
        type: string
      firstName:
        type: string
      lastName:
        type: string
      email:
        type: string
      password:
        type: string
      phone:
        type: string
      userStatus:
        type: integer
        format: int32
        description: User Status