Basic Structure

Swagger definitions can be written in JSON or YAML. In this guide, we only use YAML examples, but JSON works equally well. A sample Swagger specification written in YAML looks like:

1
swagger: "2.0"
2
info:
3
  title: Sample API
4
  description: API description in Markdown.
5
  version: 1.0.0
6

7
host: api.example.com
8
basePath: /v1
9
schemes:
10
  - https
11

12
paths:
13
  /users:
14
    get:
15
      summary: Returns a list of users.
16
      description: Optional extended description in Markdown.
17
      produces:
18
        - application/json
19
      responses:
20
        200:
21
          description: OK

Metadata

Every Swagger specification starts with the Swagger version, 2.0 being the latest version. A Swagger version defines the overall structure of an API specification – what you can document and how you document it.

1
swagger: "2.0"

Then, you need to specify the API info – title, description (optional), version (API version, not file revision or Swagger version).

1
info:
2
  title: Sample API
3
  description: API description in Markdown.
4
  version: 1.0.0

version can be a random string. You can use major.minor.patch (as in semantic versioning), or an arbitrary format like 1.0-beta or 2016.11.15. description can be multiline and supports GitHub Flavored Markdown for rich text representation. info also supports other fields for contact information, license and other details. Reference: Info Object.

Base URL

The base URL for all API calls is defined using schemes, host and basePath:

1
host: api.example.com
2
basePath: /v1
3
schemes:
4
  - https

All API paths are relative to the base URL. For example, /users actually means https://api.example.com/v1/users. More info: API Host and Base URL.

Consumes, Produces

The consumes and produces sections define the MIME types supported by the API. The root-level definition can be overridden in individual operations.

1
consumes:
2
  - application/json
3
  - application/xml
4
produces:
5
  - application/json
6
  - application/xml

More info: MIME Types.

Paths

The paths section defines individual endpoints (paths) in your API, and the HTTP methods (operations) supported by these endpoints. For example, GET /users can be described as:

1
paths:
2
  /users:
3
    get:
4
      summary: Returns a list of users.
5
      description: Optional extended description in Markdown.
6
      produces:
7
        - application/json
8
      responses:
9
        200:
10
          description: OK

More info: Paths and Operations.

Parameters

Operations can have parameters that can be passed via URL path (/users/{userId}), query string (/users?role=admin), headers (X-CustomHeader: Value) and request body. You can define the parameter types, format, whether they are required or optional, and other details:

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
          minimum: 1
11
          description: Parameter description in Markdown.
12
      responses:
13
        200:
14
          description: OK

More info: Describing Parameters.

Responses

For each operation, you can define possible status codes, such as 200 OK or 404 Not Found, and schema of the response body. Schemas can be defined inline or referenced from an external definition via $ref. You can also provide example responses for different content types.

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
          minimum: 1
11
          description: The ID of the user to return.
12
      responses:
13
        200:
14
          description: A User object.
15
          schema:
16
            type: object
17
            properties:
18
              id:
19
                type: integer
20
                example: 4
21
              name:
22
                type: string
23
                example: Arthur Dent
24
        400:
25
          description: The specified user ID is invalid (e.g. not a number).
26
        404:
27
          description: A user with the specified ID was not found.
28
        default:
29
          description: Unexpected error

More info: Describing Responses.

Input and Output Models

The global definitions section lets you define common data structures used in your API. They can be referenced via $refwhenever a schema is required – both for request body and response body. For example, this JSON object:

1
{
2
  "id": 4,
3
  "name": "Arthur Dent"
4
}

can be represented as:

1
definitions:
2
  User:
3
    properties:
4
      id:
5
        type: integer
6
      name:
7
        type: string
8
    # Both properties are required
9
    required:
10
      - id
11
      - name

and then referenced in the request body schema and response body schema as follows:

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
      responses:
11
        200:
12
          description: OK
13
          schema:
14
            $ref: "#/definitions/User"
15
  /users:
16
    post:
17
      summary: Creates a new user.
18
      parameters:
19
        - in: body
20
          name: user
21
          schema:
22
            $ref: "#/definitions/User"
23
      responses:
24
        200:
25
          description: OK

Authentication

The securityDefinitions and security keywords are used to describe the authentication methods used in your API.

1
securityDefinitions:
2
  BasicAuth:
3
    type: basic
4

5
security:
6
  - BasicAuth: []

Supported authentication methods are:

Basic authentication
API key (as a header or query parameter)
OAuth 2 common flows (implicit, password, application and access code)

More info: Authentication.

Did not find what you were looking for? Ask the community
Found a mistake? Let us know