Overview of the Swagger schema format

The following code sample is a Swagger schema template that you use in creating the Swagger schema for a REST API.

swagger: '2.0'
info:
  description: "Description of API"
  version: '1.0'
  title: "Name of API"
basePath: <base_path> # Base path prepended to every path in this API
                        # Generally takes the form /grouping/version, such as /policies/v1
x-gw-schema-import:
  <alias>: <JSON_schema_name> # Can include any number of imports, but this API requires just one
produces: # Used as the default for operations that do not explicitly declare it
- application/json
consumes: # Used as the default for operations that do not explicitly declare it
- application/json
paths:
  /<path>:
    <HTTP_operation>: # Operations are in lower-case: get, post, patch, delete
      summary: <summary> # Any text you like
      description: <description> # Any text
      operationId: <operationId> # Becomes the handler method name, must be unique within this schema
      parameters: # Possible to omit if the method has no parameters. 
                  # Parameters is a list, so prefix each element with '-' (dash) to indicate that it is a list item
      - name: <foo>
        in: <query|path|body|header> # Must be either query, path, body, or header
        required: <true|false> # Defaults to false, must be set to true for path parameters
        type: <string|integer|number|boolean> # Use only with query, path, or header parameters
        schema: # Only include if using a parameter of type body
          $ref: <alias>#/definitions/<name>
      responses:
        '<code>': # Value must be enclosed in either single or double quotes.  
                  # Use 200 is generic success status, 201 for "created", 204 for responses without a body
          description: <description>
          schema: # Only include for a 201 or 204
            $ref: <alias>#/definitions/<name>