Basic Structure

You can write OpenAPI definitions in YAML or JSON. In this guide, we use only YAML examples but JSON works equally well. A sample OpenAPI 3.0 definition written in YAML looks like:

1
openapi: 3.0.0
2
info:
3
  title: Sample API
4
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
5
  version: 0.1.9
6

7
servers:
8
  - url: http://api.example.com/v1
9
    description: Optional server description, e.g. Main (production) server
10
  - url: http://staging-api.example.com
11
    description: Optional server description, e.g. Internal staging server for testing
12

13
paths:
14
  /users:
15
    get:
16
      summary: Returns a list of users.
17
      description: Optional extended description in CommonMark or HTML.
18
      responses:
19
        "200": # status code
20
          description: A JSON array of user names
21
          content:
22
            application/json:
23
              schema:
24
                type: array
25
                items:
26
                  type: string

All keyword names are case-sensitive.

Metadata

Every API definition must include the version of the OpenAPI Specification that this definition is based on:

1
openapi: 3.0.0

The OpenAPI version defines the overall structure of an API definition – what you can document and how you document it. OpenAPI 3.0 uses semantic versioning with a three-part version number. The available versions are 3.0.0, 3.0.1, 3.0.2, and 3.0.3; they are functionally the same.

The info section contains API information: title, description (optional), version:

1
info:
2
  title: Sample API
3
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
4
  version: 0.1.9

title is your API name. description is extended information about your API. It can be multiline and supports the CommonMark dialect of Markdown for rich text representation. HTML is supported to the extent provided by CommonMark (see HTML Blocks in CommonMark 0.27 Specification). version is an arbitrary string that specifies the version of your API (do not confuse it with file revision or the openapi version). You can use semantic versioning like major.minor.patch, or an arbitrary string like 1.0-beta or 2017-07-25. info also supports other keywords for contact information, license, terms of service, and other details.

Reference: Info Object.

Servers

The servers section specifies the API server and base URL. You can define one or several servers, such as production and sandbox.

1
servers:
2
  - url: http://api.example.com/v1
3
    description: Optional server description, e.g. Main (production) server
4
  - url: http://staging-api.example.com
5
    description: Optional server description, e.g. Internal staging server for testing

All API paths are relative to the server URL. In the example above, /users means http://api.example.com/v1/users or http://staging-api.example.com/users, depending on the server used. For more information, see API Server and Base Path.

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 CommonMark or HTML
6
      responses:
7
        "200":
8
          description: A JSON array of user names
9
          content:
10
            application/json:
11
              schema:
12
                type: array
13
                items:
14
                  type: string