OpenAPI Specification Path
Internal
Overview
The top level paths keyword introduce a map of paths, keyed by their path value:
[...] paths: /a: [...] /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.
/a: [...] summary: description: get: [...] put: [...] post: [...] delete: [...] options: [...] head: [...] patch: [...] trace: [...] parameters: [...] servers:
Path Templating
Path templating refers to the usage of curly braces {} to mark a section of a URL path as replaceable using path parameters.
Operations
An operation represents a single HTTP operation on a path.
Valid operations:
getputpostdeleteoptionsheadpatchtrace
get|put|post|delete|options|head|patch|trace:
summary: |
A short description of the operation.
operationId: GetPets
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.
oapi-codegen uses operationId as a base for a various function and struct names in client and server generated code. All names get their first character upper-cased, making them exported, regardless of whether the first character of the operationId is lower or upper case. For:
paths:
/pets:
get:
operationId: GetPets
[...]
oapi-codegen generates:
[...]
// The interface specification for the client above.
type ClientInterface interface {
// GetPets request
GetPets(ctx context.Context, params *GetPetsParams, reqEditors ...RequestEditorFn) (*http.Response, error)
}
[...]
// ServerInterface represents all server handlers.
type ServerInterface interface {
// (GET /pets)
GetPets(ctx echo.Context, params GetPetsParams) error
}
[...]
summary
Surfaces in the generated code, as the generated server interface method comment.
description
responses
The responses field is required and lists all possible HTTP responses that may result from executing this operation.
Response
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:
/pets:
get:
[...]
responses:
200:
description: Return all the pets the user has access to, as a list.
headers: [...]
links: [...]
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
An empty response:
paths:
/a:
get:
[...]
responses:
200:
schema:
$ref: '#/components/schemas/Empty'
The Empty type is declared in the /components/schemas as such:
headers
requestBody
Also see:
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
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". An operation accepts multiple parameters, which should be specified as an array.
get:
[...]
parameters:
- name: Color
in: path|query|header|cookie
description:
required: true|false
style: form
schema: [...]
deprecated: true|false
allowEmptyValue: true|false
- [...]
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:
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:
Header Parameters
Header parameters are key value pairs that can be used to configure the behavior of the API.
Also see:
Cookie Parameters
Parameter Schema
paths:
/pets:
get:
parameters:
- name: tags
[...]
schema:
type: array
items:
type: string
Examples
TODEPLETE
Response
A response is defined by its HTTP status code and the data returned in the response body and/or headers.
200:
description: 200 response
schema:
$ref: '#/definitions/Empty'
originalRef: '#/definitions/Empty'
headers:
Access-Control-Allow-Origin:
type: 'string'
Access-Control-Allow-Methods:
type: 'string'
Access-Control-Allow-Headers:
type: 'string'
description
The description is required. Represents a short description of the response.
Response Body
schema
The schema keyword is used to describe the response body. A schema may define:
- a primitive type such as "string" or "number", used for plain text responses. Note that Amazon API Gateway warns if it encounters a primitive type.
- an object
- an array – typically used with JSON and XML APIs
- a file
- a reference - the schema can be defined in-line or defined at the root level of the document and referenced via $ref. This is useful if multiple responses share the same schema.
For reference models (RefModel), model.setReference("RefName") puts the model in the correct state to refer to:
definitions:
RefName:
type: ...
In-line schema:
responses:
200:
description: something
schema:
type: object
properties:
id:
type: integer
description: The user ID.
username:
type: string
description: The user name.
This is an example that uses references:
responses:
200:
description: something
schema:
$ref: '#/definitions/User'
...
definitions:
User:
type: object
properties:
id:
type: integer
description: The user ID.
username:
type: string
description: The user name.
"responseSchema" is sometimes used, but that seems to be deprecated.
Empty Response Body
For responses that have no body, like 204 No Content, no "schema" should be specified. This is conventionally treated as no-body response.
Response Headers
Responses can include custom headers, or headers that implement a protocol like CORS.
headers
The custom headers must be declared, under the "headers" section of the response. For OpenAPI 2.0, there is no way in Swagger to define common response headers for different response codes or different API operations. You need to define the headers for each response individually. "headers" is aA container that maps a header name to its definition. The header names are case insensitive. If a header is specified by the an extension, such as x-amazon-apigateway-integration, it has to be declared in the headers section for the corresponding response, otherwise a template error is generated.
200:
description: 200 response
...
headers:
Access-Control-Allow-Origin:
type: 'string'
Access-Control-Allow-Methods:
type: 'string'
Access-Control-Allow-Headers:
type: 'string'
schema:
$ref: '#/definitions/Empty'
originalRef: '#/definitions/Empty'
Reference Object
CORS
More:
x-nullable
Appears in automatically generated Swagger files, as such:
definitions:
LibraryAccount:
type: object
required:
- name
properties:
name:
type: string
x-nullable: true
definitions:
A:
type: string
title: A
x-nullable: true
When used for an API Gateway import, it errors out as:
Unable to create model for 'LibraryAccount': Invalid model specified: Validation Result: warnings : [], errors : [Invalid model schema specified. Unsupported keyword(s): ["x-nullable"]]