Skip to content

Paths and Operations

In OpenAPI terms, paths are endpoints (resources), such as /users or /reports/summary/, that your API exposes, 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 the API server URL. The full request URL is constructed as <server-url>/path. Global servers can also be overridden on the path level or operation level (more on that below). Paths may have an optional short summary and a longer description for documentation purposes. This information is supposed to be relevant to all operations in this path. description can be multi-line and supports Markdown (CommonMark) for rich text representation.

1
paths:
2
  /users/{id}:
3
    summary: Represents a user
4
    description: >
5
      This resource represents an individual user in the system.
6
      Each user is identified by a numeric `id`.
7


8
    get: ...
9
    patch: ...
10
    delete: ...

Path Templating

You can use curly braces {} to mark parts of an 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. OpenAPI 3.0 supports get, post, put, patch, delete, head, options, and trace. 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. OpenAPI 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). Below is a minimal example of an operation:

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

Here is a more detailed example with parameters and response schema:

1
paths:
2
  /users/{id}:
3
    get:
4
      tags:
5
        - Users
6
      summary: Gets a user by ID.
7
      description: >
8
        A detailed description of the operation.
9
        Use markdown for rich text representation,
10
        such as **bold**, *italic*, and [links](https://swagger.io).
11
      operationId: getUserById
12
      parameters:
13
        - name: id
14
          in: path
15
          description: User ID
16
          required: true
17
          schema:
18
            type: integer
19
            format: int64
20
      responses:
21
        "200":
22
          description: Successful operation
23
          content:
24
            application/json:
25
              schema:
26
                $ref: "#/components/schemas/User"
27
      externalDocs:
28
        description: Learn more about user operations provided by this API.
29
        url: http://api.example.com/docs/user-operations/
30


31
components:
32
  schemas:
33
    User:
34
      type: object
35
      properties:
36
        id:
37
          type: integer
38
          format: int64
39
        name:
40
          type: string
41
      required:
42
        - id
43
        - name

Operations also support some optional elements for documentation purposes:

  • A short summary and a longer description of what an operation does. description can be multi-line and supports Markdown (CommonMark) for rich text representation.
  • tags – used to group operations logically by resources or any other qualifier. See Grouping Operations With Tags.
  • externalDocs – used to reference an external resource that contains additional documentation.

Operation Parameters

OpenAPI 3.0 supports operation parameters passed via path, query string, headers, and cookies. You can also define the request body for operations that transmit data to the server, such as POST, PUT and PATCH. For details, see Describing Parameters and Describing Request Body.

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
          schema:
8
            type: string
9
            enum: [user, poweruser, admin]
10
          required: true

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 OpenAPI 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

operationId

operationId is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.

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
    ...

Some common use cases for operationId are:

  • Some code generators use this value to name the corresponding methods in code.
  • Links can refer to the linked operations by operationId.

Deprecated Operations

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

Overriding Global Servers

The global servers array can be overridden on the path level or operation level. This is useful if some endpoints use a different server or base path than the rest of the API. Common examples are:

  • Different base URL for file upload and download operations.

  • Deprecated but still functional endpoints.

    servers:

1
paths:
2
  /files:
3
    description: File upload and download operations
4
    servers:
5
      - url: https://files.example.com
6
        description: Override base path for all operations with the /files path
7
    ...
8


9
/ping:
10
    get:
11
      servers:
12
        - url: https://echo.example.com
13
          description: Override base path for the GET /ping operation

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

Swagger Open Source
Swagger
Pro Tools
Resources