OpenAPI Specification Path

Internal

• OpenAPI Specification

Overview

The top level paths keyword introduce a map of paths, keyed by their path value:

[...]
paths:
 /a:
    summary:
    description: 
    get: [...]
    put: [...]
    post: [...]
    delete: [...]
    options: [...]
    head: [...]
    patch: [...]
    trace: [...]
    parameters: [...]
    servers:
 /b:
   [...]
 /c:
   [...]
[...]

Path

Each path name must start with a forward slash "/". The path is appended to the expanded URL from the server object url field in order to construct the full URL. Path templating is allowed. Each path accepts zero or more of the available operations (get, put, post, delete, options, head, patch, trace) and parameters, which is a list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at operation level but cannot be removed there.

Path Templating

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating

Path templating refers to the usage of curly braces {} to mark a section of a URL path as replaceable using path parameters.

Operations

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject

An operation represents a single HTTP operation on a path.

get|put|post|delete|options|head|patch|trace:
  summary: |
     A short description of the operation.
  operationId: someOperationId
  description:  '...'
  parameters: [...]
  responses: [...]
  tags: [...]
  requestBody:
  callbacks:
  security:
  servers:
  deprecated:

operationId

A unique string, among all operations described by this API, used to identify the operation. The operationId value is case-sensitive. Tools and libraries may use operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.

Responses

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object

The responses field is required and lists all possible HTTP responses that may result from executing this operation. The element must contain at least one response code. The definition is not expected to cover all possible HTTP response codes, because they may not be known in advance. However, the definition should cover a successful operation response and any known errors. The "default" map key may be used as a default response object for all HTTP codes that are not covered individually in the definition.

paths:
 /a:
   get:
     responses:
       200:
         [...]
       default:
         [...]

RequestBody

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#request-body-object

Also see:

REST Request Body

Tags

Each operation can be annotated with a list of tags. Tagged operations may be handled differently by tools and libraries. Optionally, each tag can get a "description" and an "externalDocs" in the global "tags" section on the root level. The tag names here should match those used in operations. The tag order in the global tags section also controls the default sorting in the UI. It is possible to use a tag at operation level even if it is not specified on the root level.

tags:
  - name: tag-a
    description: Something that would shed light on tag-a semantics
    externalDocs:
      url: https://example.com/my-docs/tag-a.html
paths:
  /a:
    get:
      tags:
        - tag-a
        - other-tag

Parameters

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject

A unique parameter is defined by a combination of a name and a location.

get:
  [...]
  parameters:
    - name: id
      in: path|query|header|cookie
      description:
      required: true|false
      deprecated: true|false
      allowEmptyValue: true|false
      schema: [...]
    - [...]

An operation accepts multiple parameters.

A unique parameter is defined by a combination of its name, defined as value of the name field, and its location, defined as value of the in field. The name value is required and case sensitive.

There are four possible parameter locations: "query", "header", "path", "cookie".

Parameter Locations

Path Parameters

A path parameter is declared as in: path in the OpenAPI specification file, and is a URL fragment at the left side of the question mark in the URL. For "path" parameters, the parameter name must correspond to a template expression occurring in the path field. The parameter value is actually part of the operation's URL. Also, the required property is required and the value must be true.

 /query/{id}

paths:
 /query/{id}:
   get:
     - name: id
       in: path
       required: true
       [...]

Also see:

REST Path Parameters

Query Parameters

A query parameter is declared as in: query in the OpenAPI specification file, and it is an URL fragment that follows the question mark in the full URL.

allowEmptyValue field is valid only for query parameters and allows sending a parameter with an empty value. The default value is false. Use of this property is not recommended and it is likely to be removed in a later revision.

Also see:

REST Query Parameters

Header Parameters

Header parameters are key value pairs that can be used to configure the behavior of the API.

Also see:

REST Request Headers

Examples

GET with Empty Response Body

paths:
  /a:
    get:
      parameters:
        - name: test
          in: query
          type: string
      responses:
        200:
          schema:
            $ref: '#/components/schemas/Empty'
components:
  schemas:
    Empty:
      type: object