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