Last updated

Path Item Object

Excerpt from the OpenAPI 3.1 specification about the Path Item object

Path Item Object

Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.

Fixed Fields
Field NameTypeDescription
$refstringAllows for a referenced definition of this path item. The referenced structure MUST be in the form of a Path Item Object. In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving Relative References.
summarystringAn optional, string summary, intended to apply to all operations in this path.
descriptionstringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
getOperation ObjectA definition of a GET operation on this path.
putOperation ObjectA definition of a PUT operation on this path.
postOperation ObjectA definition of a POST operation on this path.
deleteOperation ObjectA definition of a DELETE operation on this path.
optionsOperation ObjectA definition of a OPTIONS operation on this path.
headOperation ObjectA definition of a HEAD operation on this path.
patchOperation ObjectA definition of a PATCH operation on this path.
traceOperation ObjectA definition of a TRACE operation on this path.
servers[Server Object]An alternative server array to service all operations in this path.
parameters[Parameter Object | Reference Object]A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.

This object MAY be extended with Specification Extensions.

Path Item Object Example
{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*' :
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    items:
      type: string
  style: simple

Visuals

Redocly renders each operation. The HTTP method renders as a badge in the sidebar navigation as well as next to the operation summary.

Redocly renders the path within each path item's corresponding operations.

root path item

results path item

Types

  • PathItem
const PathItem: NodeType = {
  properties: {
    $ref: { type: 'string' },
    servers: listOf('Server'),
    parameters: listOf('Parameter'),
    summary: { type: 'string' },
    description: { type: 'string' },
    get: 'Operation',
    put: 'Operation',
    post: 'Operation',
    delete: 'Operation',
    options: 'Operation',
    head: 'Operation',
    patch: 'Operation',
    trace: 'Operation',
  },
};

The PathItem type has a close relationship to the Operation type.

PathsPathItemParameterOperationServerhashashashas