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 /users or /reports/summary, and operations are the HTTP methods used to manipulate these paths, such as GET, POST or DELETE.

Paths

API paths and operations are defined in the global paths section of the API specification.

paths: /ping: … /users: … /users/{id}: …

All paths are relative to basePath (see API Host and Base URL). The full request URL is constructed as scheme://host/basePath/path.

Path Templating

Read more: Disney character generator

Swagger supports path templating, meaning you can use curly braces {} to mark parts of a URL as path parameters:

/users/{id} /organizations/{orgId}/members/{memberId} /report.{format}

The API client needs to provide appropriate parameter values when making an API call, such as /users/5 or /users/12.

Operations

For each path, you define operations (HTTP methods) that can be used to access that path. Swagger 2.0 supports get, post, put, patch, delete, head, and options. A single path can support multiple operations, for example, GET /users to get a list of users and POST /users 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:

paths: /ping: get: responses: 200: description: OK

More detailed example with parameters and response schema:

paths: /users/{id}: get: summary: Gets a user by ID. description: > 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). operationId: getUsers tags: – users produces: – application/json – application/xml parameters: – name: id in: path description: User ID type: integer required: true responses: 200: description: OK schema: $ref: ‘#/definitions/User’ externalDocs: url: http://api.example.com/docs/user-operations/ description: Learn more about User operations provided by this API. definitions: User: type: object properties: id: type: integer name: type: string required: – id – name

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.

Operation Parameters

Read more: M shadows long hair

Swagger supports operation parameters passed via path, query string, headers and request body. For details, see Describing Parameters.

operationId

Each operation may specify a unique operationId. Some code generators use this value to name the corresponding methods in code.

/users: get: operationId: getUsers summary: Gets all users. … post: operationId: addUser summary: Adds a new user. … /user/{id}: get: operationId: getUserById 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 instead. Incorrect:

paths: /users?role={role}:

Correct:

paths: /users: get: parameters: – in: query name: role type: string enum: [user, poweruser, admin] required: false

Read more: Burnt copper hair color

This also means that it is impossible to have multiple paths that differ only in query string, such as:

GET /users?firstName=value&lastName=value GET /users?role=value

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:

GET /users/findByName?firstName=value&lastName=value GET /users/findByRole?role=value

Marking as Deprecated

You can mark specific operations as deprecated to indicate that they should be transitioned out of usage:

/pet/findByTags: get: deprecated: true

Tools may handle deprecated operations in a specific way. For example, Swagger UI displays them with a different style:

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