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 Name | Type | Description |
|---|---|---|
$ref | string | Allows 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. |
| summary | string | An optional, string summary, intended to apply to all operations in this path. |
| description | string | An optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation. |
| get | Operation Object | A definition of a GET operation on this path. |
| put | Operation Object | A definition of a PUT operation on this path. |
| post | Operation Object | A definition of a POST operation on this path. |
| delete | Operation Object | A definition of a DELETE operation on this path. |
| options | Operation Object | A definition of a OPTIONS operation on this path. |
| head | Operation Object | A definition of a HEAD operation on this path. |
| patch | Operation Object | A definition of a PATCH operation on this path. |
| trace | Operation Object | A 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: simpleVisuals
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.
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.