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:
1swagger: "2.0"2info:3 title: Sample API4 description: API description in Markdown.5 version: 1.0.06
7host: api.example.com8basePath: /v19schemes:10 - https11
12paths:13 /users:14 get:15 summary: Returns a list of users.16 description: Optional extended description in Markdown.17 produces:18 - application/json19 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.
1swagger: "2.0"
Then, you need to specify the API info
– title
, description
(optional), version
(API version, not file revision or Swagger version).
1info:2 title: Sample API3 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
:
1host: api.example.com2basePath: /v13schemes: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.
1consumes:2 - application/json3 - application/xml4produces:5 - application/json6 - 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:
1paths:2 /users:3 get:4 summary: Returns a list of users.5 description: Optional extended description in Markdown.6 produces:7 - application/json8 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:
1paths:2 /users/{userId}:3 get:4 summary: Returns a user by ID.5 parameters:6 - in: path7 name: userId8 required: true9 type: integer10 minimum: 111 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.
1paths:2 /users/{userId}:3 get:4 summary: Returns a user by ID.5 parameters:6 - in: path7 name: userId8 required: true9 type: integer10 minimum: 111 description: The ID of the user to return.12 responses:13 200:14 description: A User object.15 schema:16 type: object17 properties:18 id:19 type: integer20 example: 421 name:22 type: string23 example: Arthur Dent24 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 $ref
whenever 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:
1definitions:2 User:3 properties:4 id:5 type: integer6 name:7 type: string8 # Both properties are required9 required:10 - id11 - name
and then referenced in the request body schema and response body schema as follows:
1paths:2 /users/{userId}:3 get:4 summary: Returns a user by ID.5 parameters:6 - in: path7 name: userId8 required: true9 type: integer10 responses:11 200:12 description: OK13 schema:14 $ref: "#/definitions/User"15 /users:16 post:17 summary: Creates a new user.18 parameters:19 - in: body20 name: user21 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.
1securityDefinitions:2 BasicAuth:3 type: basic4
5security: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