Swagger tutorial

Swagger is an alternative format to API Blueprint for describing your API that you can use in Apiary. This page showcases basic syntax of Swagger API Description.

Tip

For details on how to use Swagger in Apiary and what is supported, see dedicated Swagger page. Also feel free to compare Swagger with API Blueprint.

Swagger

Swagger is open sourced format for describing APIs.

This is how Swagger looks like:

swagger: '2.0'
info:
  title: Polls Swagger
  description: Polls is a simple API allowing consumers to view polls and vote in them.
  version: "8234aab51481d37a30757d925b7f4221a659427e"
host: polls.apiblueprint.org
schemes:
  - https
paths:
  /questions:
    x-summary: Questions Collection
    x-description: ''
    get:
      summary: List all questions
      responses:
        200:
          description: 'List'
          examples:
            application/json:
              - question: "Favourite programming language?"
                published_at: "2015-08-05T08:40:51.620Z"
                choices:
                  - choice: "Swift"
                    votes: 2048
                  - choice: "Python"
                    votes: 1024
                  - choice: "Objective-C"
                    votes: 512
                  - choice: "Ruby"
                    votes: 256

Writing Swagger

YAML by default

We are showing Swagger only in YAML format, because that’s how it’s supported in Apiary, but Swagger in JSON format will work the same.

Choosing editor

If you are new to API Description world, best choice is to use either Apiary Editor on Apiary.io, because of its built-in helpers and instant preview or dedicated Swagger Editor.

Metadata, API Name & Description

Every Swagger document starts with Swagger version declaration swagger: "2.0". Then you can specify info object for additional metadata. title and version are required parameters, others like description are optional. See Known limitations on what parameters are not supported.

URL definition

schemes is an array protocols supported by API. You can specify them like so: [http, https]. Apiary will use https if defined
host is domain for API
basePath defines URL prefix for all defined endpoints.

For example, defining /account endpoint actually means scheme://host/basePath/account

Paths

paths: object defines endpoints in your API. x-summary and x-description are Apiary defined Swagger extensions.

Operations

Operations (like get or post) on paths defines actions. In Apiary documentation, summary will be used as action title, and description as action description.

Limitations

Swagger doesn’t support some features:

Example values of HTTP headers (see our x-example extension)
Multiple requests

Using `operationId`

Each operation can specify operationId. In Apiary documentation it’s used for rendering Action relation.

Operation responses

You can describe multiple responses, for different content-types.

Limitations

Swagger doesn’t support some features:

Response headers
Request-Response pairing
Response names

Definitions

definitions have same goal as MSON. Make it easy to describe data structures and use them in API Description. Unlike MSON, definitions in Swagger are using JSON Schema and JSON Schema referencing for use inside API Description. Here is an example API using definitions:

swagger: "2.0"
info:
  version: 1.0.0
  title: swagger-demo
  description: Description of the API in Markdown
host: petstore.swagger.io
tags:
  - greeting
basePath: /api
schemes: [http]
paths:
  /message/{name}:
    x-summary: Message operations
    x-description: Operation description in Markdown
    get:
      summary: Get a message of the day
      description: |
       Description of the operation in Markdown
      operationId: getMessage
      parameters:
        - name: name
          in: query
          description: name to include in the message
          type: string
          x-example: 'Hello, Adam!'
      responses:
        default:
          description: Bad request
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/Message'
          examples:
            'application/json':
              message: 'Hello, Adam!'
definitions:
  Message:
    required:
      - message
    properties:
      message:
        type: string
        default: 'Hello, Adam!'