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.

1
paths:
2
  /ping: ...
3
  /users: ...
4
  /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

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

1
/users/{id}
2
/organizations/{orgId}/members/{memberId}
3
/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:

1
paths:
2
  /ping:
3
    get:
4
      responses:
5
        200:
6
          description: OK

More detailed example with parameters and response schema:

1
paths:
2
  /users/{id}:
3
    get:
4
      summary: Gets a user by ID.
5
      description: >
6
        A detailed description of the operation.
7
        GitHub Flavored Markdown can be used for rich text representation,
8
        such as **bold**, *italic* and [links](https://swagger.io).
9
      operationId: getUsers
10
      tags:
11
        - users
12
      produces:
13
        - application/json
14
        - application/xml
15
      parameters:
16
        - name: id
17
          in: path
18
          description: User ID
19
          type: integer
20
          required: true
21
      responses:
22
        200:
23
          description: OK
24
          schema:
25
            $ref: "#/definitions/User"
26
      externalDocs:
27
        url: http://api.example.com/docs/user-operations/
28
        description: Learn more about User operations provided by this API.
29
definitions:
30
  User:
31
    type: object
32
    properties:
33
      id:
34
        type: integer
35
      name:
36
        type: string
37
    required:
38
      - id
39
      - 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

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.

1
/users:
2
    get:
3
      operationId: getUsers
4
      summary: Gets all users.
5
      ...
6
    post:
7
      operationId: addUser
8
      summary: Adds a new user.
9
      ...
10
  /user/{id}:
11
    get:
12
      operationId: getUserById
13
      summary: Gets a user by user ID.
14
      ...

Query String in Paths

Query string parameters must not be included in paths. They should be defined as query parameters instead. Incorrect:

1
paths:
2
  /users?role={role}:

Correct:

1
paths:
2
  /users:
3
    get:
4
      parameters:
5
        - in: query
6
          name: role
7
          type: string
8
          enum: [user, poweruser, admin]
9
          required: false

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

1
GET /users?firstName=value&lastName=value
2
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:

1
GET /users/findByName?firstName=value&lastName=value
2
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:

1
/pet/findByTags:
2
  get:
3
    deprecated: true

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

Deprecated operation in Swagger UI

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