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

Last updated on