OAS 2 This page applies to OpenAPI Specification ver. 2 (fka Swagger).
To learn about the latest version, visit OpenAPI 3 pages.
Paths and Operations
In Swagger terms, paths
are endpoints (resources) that your API exposes, such as
, and operations
are the HTTP methods used to manipulate these paths, such as GET, POST or DELETE.
API paths and operations are defined in the global
section of the API specification.
All paths are relative to
(see API Host and Base URL
). The full request URL is constructed as
Swagger supports path templating, meaning you can use curly braces
to mark parts of a URL as path parameters
The API client needs to provide appropriate parameter values when making an API call, such as
For each path, you define operations (HTTP methods) that can be used to access that path. Swagger 2.0 supports
A single path can support multiple operations, for example,
to get a list of users and
to add a new user. Swagger defines a unique operation as a combination of a path and an HTTP method. This means that two GET or two POST methods for the same path are not allowed – even if they have different parameters (parameters have no effect on uniqueness).
Minimal example of an operation:
More detailed example with parameters and response schema:
summary: Gets a user by ID.
A detailed description of the operation.
GitHub Flavored Markdown can be used for rich text representation,
such as **bold**, *italic* and [links](https://swagger.io).
- name: id
description: User ID
description: Learn more about User operations provided by this API.
Operations support some optional elements for documentation purposes:
- A short
summary and a longer
description of what the operation does.
description can be multi-line and supports GitHub Flavored Markdown for rich text representation.
tags are used to group operations in Swagger UI.
externalDocs allows referencing an external resource that contains additional documentation.
Swagger supports operation parameters passed via path, query string, headers and request body. For details, see Describing Parameters
Each operation may specify a unique
. Some code generators use this value to name the corresponding methods in code.
summary: Gets all users.
summary: Adds a new user.
summary: Gets a user by user ID.
Query String in Paths
Query string parameters must not
be included in paths. They should be defined as query parameters
- in: query
enum: [user, poweruser, admin]
This also means that it is impossible to have multiple paths that differ only in query string, such as:
This is because Swagger considers a unique operation as a combination of a path and the HTTP method, and additional parameters do not make the operation unique. Instead, you should use unique paths such as:
Marking as Deprecated
You can mark specific operations as
to indicate that they should be transitioned out of usage:
Tools may handle deprecated operations in a specific way. For example, Swagger UI displays them with a different style: