Skip to Content
OpenAPI HubPaths

Paths Object in OpenAPI

The paths object is a map of Path Item Objects that describes the available paths and operations for the API.

Each path is a relative path to the servers defined in the Servers object, either at the document, path, or operation level. For example, if a server is defined as https://speakeasy.bar/api and a path is defined as /drinks, the full URL to the path would be https://speakeasy.bar/api/drinks, where the path is appended to the server URL.

Example:

paths:
  /drinks:
    get: ... # operation definition
  /drink:
    get: ... # operation definition
    put: ... # operation definition
    post: ... # operation definition
    delete: ... # operation definition
Field
Required
Description
A relative path to an individual endpoint, where the path must begin with a
.
Required
Description
Any number of extension fields can be added to the paths object that can be used by tooling and vendors.

Path Item Object in OpenAPI

A Path Item Object describes the operations available on a single path. This is generally a map of HTTP methods to Operation Objects that describe the operations available.

It is possible to override the Servers defined at the document level for a specific path by providing a list of Server Objects at the path level.

It is also possible to provide a list of Parameters that are common to all operations defined on the path.

Example:

paths:
  /drinks:
    summary: Various operations for browsing and searching drinks
    description:
    servers: # Override the servers defined at the document level and apply to all operations defined on this path
      - url: https://drinks.speakeasy.bar
        description: The drinks server
    parameters: # Define a list of parameters that are common to all operations defined on this path
      - name: type
        in: query
        schema:
          type: string
          enum:
            - cocktail
            - mocktail
            - spirit
            - beer
            - wine
            - cider
    get: ... # operation definition

Or:

paths:
  /drinks:
    $ref: "#/components/pathItems/drinks" # Reference a Path Item Object defined in the Components Object allowing for reuse in different paths
components:
  pathItems:
    drinks:
      servers:
        - url: https://drinks.speakeasy.bar
          description: The drinks server
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum:
              - cocktail
              - mocktail
              - spirit
              - beer
              - wine
              - cider
      get: ... # operation definition
Field
Type
String
Required
Description
Allows for referencing a Path Item Object defined in the Components Object under the
field. If used, no other fields should be set.
Type
String
Required
Description
A short summary of what the path item represents. This may contain CommonMark syntax  to provide a rich description.
Type
String
Required
Description
A description of the path item. This may contain CommonMark syntax  to provide a rich description.
Required
Description
A list of Server Objects that override the servers defined at the document level. Applies to all operations defined on this path.
Required
Description
A list of Parameter Objects that are common to all operations defined on this path.
Required
Description
An operation associated with the
HTTP method.
Required
Description
An operation associated with the
HTTP method.
Required
Description
An operation associated with the
HTTP method.
Required
Description
An operation associated with the
HTTP method.
Required
Description
An operation associated with the
HTTP method.
Required
Description
An operation associated with the
HTTP method.
Required
Description
An operation associated with the
HTTP method.
Required
Description
An operation associated with the
HTTP method.
Required
Description
An operation associated with the
HTTP method. Safe and idempotent, like
, but allows a request body for complex queries. Available in OpenAPI v3.2.0+.
Type
Map[String, Operation Object]
Required
Description
A map of non-standard HTTP methods to Operation Objects, enabling documentation of custom methods beyond those defined by the specification. Available in OpenAPI v3.2.0+.
Required
Description
Any number of extension fields can be added to the Path Item Object that can be used by tooling and vendors.

The order of fields above is recommended but is not significant to the order in which the endpoints should be used.

OpenAPI 3.2 path features

OpenAPI 3.2.0 introduces several new capabilities for path items.

The QUERY HTTP method

The QUERY method is a safe, idempotent HTTP method that allows clients to send query criteria in the request body rather than encoding complex parameters in the URL. This is useful for operations that require structured or lengthy query parameters that exceed practical URL length limits.

paths:
  /drinks:
    query:
      operationId: searchDrinks
      summary: Search for drinks with complex criteria
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ingredients:
                  type: array
                  items:
                    type: string
                minRating:
                  type: number
      responses:
        "200":
          description: A list of matching drinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"

Additional operations

The additionalOperations field allows defining non-standard HTTP methods as Operation Objects. This is useful for APIs that use custom HTTP methods beyond the standard set.

paths:
  /drinks/{drinkId}:
    additionalOperations:
      BREW:
        operationId: brewDrink
        summary: Brew a specific drink
        parameters:
          - name: drinkId
            in: path
            required: true
            schema:
              type: string
        responses:
          "200":
            description: Drink brewed successfully

The querystring field

OpenAPI 3.2.0 also introduces the querystring field on Operation Objects, which allows defining all query parameters as a single Schema Object instead of listing individual parameters with in: query. This simplifies the definition of operations with many query parameters or complex query structures.

paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: List available drinks
      querystring:
        type: object
        properties:
          type:
            type: string
            enum: [cocktail, mocktail, spirit, beer, wine, cider]
          limit:
            type: integer
            default: 20
          offset:
            type: integer
            default: 0
      responses:
        "200":
          description: A list of drinks

Last updated on