What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation. -The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
Occasionally, non-backwards compatible changes may be made in minor versions of the OAS where impact is believed to be low relative to the benefit provided.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the version of the OAS that it uses.
An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -289,7 +353,7 @@ OpenAPI Specification v3.1.0
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
@@ -342,8 +406,8 @@ OpenAPI Specification v3.1.0
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
OpenAPI Specification v3.1.0
description
stringA description of the API. CommonMark syntax MAY be used for rich text representation.
+A description of the API. [CommonMark] syntax MAY be used for rich text representation.
termsOfService
@@ -566,7 +630,7 @@ OpenAPI Specification v3.1.0
identifier
stringAn SPDX license expression for the API. The identifier field is mutually exclusive of the url field.
+An [SPDX] license expression for the API. The identifier field is mutually exclusive of the url field.
url
@@ -607,7 +671,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
variables
@@ -727,7 +791,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
@@ -1081,7 +1145,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1242,7 +1306,7 @@ OpenAPI Specification v3.1.0
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1414,7 +1478,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1469,7 +1533,7 @@ OpenAPI Specification v3.1.0
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1876,12 +1940,12 @@ OpenAPI Specification v3.1.0
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2382,7 +2446,7 @@ OpenAPI Specification v3.1.0
description
stringREQUIRED. A description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2392,7 +2456,7 @@ OpenAPI Specification v3.1.0
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2653,7 +2717,7 @@ OpenAPI Specification v3.1.0
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2760,7 +2824,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2859,7 +2923,7 @@ OpenAPI Specification v3.1.0
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
@@ -2973,7 +3037,7 @@ OpenAPI Specification v3.1.0
description
stringA description for the tag. CommonMark syntax MAY be used for rich text representation.
+A description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3021,7 +3085,7 @@ OpenAPI Specification v3.1.0
description
stringA description which by default SHOULD override that of the referenced component. CommonMark syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
+A description which by default SHOULD override that of the referenced component. [CommonMark] syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
@@ -3056,8 +3120,8 @@ OpenAPI Specification v3.1.0
stringOpenAPI Specification v3.1.0
identifier
stringAn SPDX license expression for the API. The identifier field is mutually exclusive of the url field.
+An [SPDX] license expression for the API. The identifier field is mutually exclusive of the url field.
stringidentifier field is mutually exclusive of the url field.identifier field is mutually exclusive of the url field.OpenAPI Specification v3.1.0
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
stringstringOpenAPI Specification v3.1.0
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
description
stringA description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringstring, Media Type Object]OpenAPI Specification v3.1.0
description
stringREQUIRED. A description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A description of the response. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
string, Media Type Object]OpenAPI Specification v3.1.0
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
@@ -2973,7 +3037,7 @@ OpenAPI Specification v3.1.0
description
stringA description for the tag. CommonMark syntax MAY be used for rich text representation.
+A description for the tag. [CommonMark] syntax MAY be used for rich text representation.
OpenAPI Specification v3.1.0
description
stringA description which by default SHOULD override that of the referenced component. CommonMark syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
+A description which by default SHOULD override that of the referenced component. [CommonMark] syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
stringdescription field, then this field has no effect.description field, then this field has no effect.OpenAPI Specification v3.1.0
The Schema Object allows the definition of input and output data types. -These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 2020-12.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation.
+These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 2020-12. +For more information about the properties, see JSON Schema Core and JSON Schema Validation.
Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics. Where JSON Schema indicates that behavior is defined by the application (e.g. for annotations), OAS also defers the definition of semantics to the application consuming the OpenAPI document.
OpenAPI Specification v3.1.0
“OAS dialect schema id”).
The following properties are taken from the JSON Schema specification but their definitions have been extended by the OAS:
-
-
- description - CommonMark syntax MAY be used for rich text representation. +
- description - [CommonMark] syntax MAY be used for rich text representation.
- format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
In addition to the JSON Schema properties comprising the OAS dialect, the Schema Object supports keywords from any other vocabularies, or entirely arbitrary properties.
@@ -3910,7 +3974,7 @@OpenAPI Specification v3.1.0
description
stringAny
-A description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
name
@@ -3928,7 +3992,7 @@ OpenAPI Specification v3.1.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
@@ -4314,7 +4378,21 @@ OpenAPI Specification v3.1.0
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-AUTHSCHEMES]
-
+ Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-2020-12]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00
+
- [JSON-Schema-Validation-2020-12]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2045]
-
Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2045
@@ -4344,6 +4422,10 @@
OpenAPI Specification v3.1.0
Returning Values from Forms: multipart/form-data. L. Masinter. IETF. July 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7578
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [SPDX]
-
+ SPDX License List. Linux Foundation. URL: https://spdx.org/licenses/
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
+
OpenAPI Specification v2.0
Version 2.0
@@ -213,13 +276,13 @@ OpenAPI Specification v2.0
Copyright © 2014 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
-The Swagger specification is licensed under The Apache License, Version 2.0.
+The Swagger specification is licensed under The Apache License, Version 2.0.
Swagger™ is a project used to describe and document RESTful APIs.
The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.
@@ -274,10 +337,10 @@ OpenAPI Specification v2.0
-The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC7231] Section 6 and in the IANA Status Code Registry.
+The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC7231] Section 6 and in the IANA Status Code Registry.
-The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to
+
The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to
represent a Swagger specification file.
For example, if a field is said to have an array value, the JSON array representation will be used:
@@ -289,7 +352,7 @@ OpenAPI Specification v2.0
All field names in the specification are case sensitive.
The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name.
-The Swagger representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.
+The Swagger representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.
By convention, the Swagger specification file is named swagger.json.
Primitive data types in the Swagger Specification are based on the types supported by the JSON-Schema Draft 4. Models are described using the Schema Object which is a subset of JSON Schema Draft 4.
@@ -1142,7 +1205,7 @@ OpenAPI Specification v2.0
Query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
Header - Custom headers that are expected as part of the request.
Body - The payload that’s appended to the HTTP request. Since there can only be one payload, there can only be one body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation.
-Form - Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded, multipart/form-data or both are used as the content type of the request (in Swagger’s definition, the consumes property of an operation). This is the only parameter type that can be used to send files, thus supporting the file type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
+ Form - Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded, multipart/form-data or both are used as the content type of the request (in Swagger’s definition, the consumes property of an operation). This is the only parameter type that can be used to send files, thus supporting the file type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult [HTML401] Section 17.13.4:
application/x-www-form-urlencoded - Similar to the format of Query parameters but as a payload. For example, foo=1&bar=swagger - both foo and bar are form parameters. This is normally used for simple parameters that are being transferred.multipart/form-data - each parameter takes a section in the payload with an internal header. For example, for the header Content-Disposition: form-data; name="submit-name" the name of the parameter is submit-name. This type of form parameters is more commonly used for file transfers.OpenAPI Specification v2.0
$ref: 'definitions.yaml#/Pet'
-The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
-Further information about the properties can be found in JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here.
+The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
+Further information about the properties can be found in JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
- $ref - As a JSON Reference
@@ -3309,7 +3372,15 @@ OpenAPI Specification v2.0
- - [RFC2119]
-
+
- [HTML401]
-
+ HTML 4.01 Specification. Dave Raggett; Arnaud Le Hors; Ian Jacobs. W3C. 27 March 2018. W3C Recommendation. URL: https://www.w3.org/TR/html401/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-04]
-
+ JSON Schema: core definitions and terminology. Draft 4. Kris Zyp; Francis Galiegue; Gary Court. Internet Engineering Task Force (IETF). 31 January 2013. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04
+
- [JSON-Schema-Validation-04]
-
+ JSON Schema: interactive and non interactive validation. Draft 4. Kris Zyp; Francis Galiegue; Gary Court. Internet Engineering Task Force (IETF). 1 February 2013. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00
+
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
- [RFC3339]
-
Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
@@ -3317,8 +3388,12 @@
OpenAPI Specification v2.0
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
-
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
+
- [RFC7159]
-
+ The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7231]
-
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.0.0
Copyright © 2017 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
-This document is licensed under The Apache License, Version 2.0.
+This document is licensed under The Apache License, Version 2.0.
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
@@ -254,15 +318,15 @@ OpenAPI Specification v3.0.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
-The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
+The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
The major.minor portion of the semver (for example 3.0) SHALL designate the OAS feature set. Typically, .patch versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.0.0 and 3.0.1 for example.
Subsequent minor version releases of the OpenAPI Specification (incrementing the minor version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 3.1.0 specification SHOULD be usable with tooling designed for 3.0.0.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -272,14 +336,14 @@ OpenAPI Specification v3.0.0
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
-- Tags MUST be limited to those allowed by the JSON Schema ruleset.
-- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
+- Tags MUST be limited to those allowed by the JSON Schema ruleset.
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
-An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.
Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00.
@@ -371,8 +435,8 @@
OpenAPI Specification v3.0.0
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
@@ -394,7 +458,7 @@ OpenAPI Specification v3.0.0
openapi
stringREQUIRED. This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. The openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.
+REQUIRED. This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. The openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.
info
@@ -455,7 +519,7 @@ OpenAPI Specification v3.0.0
description
stringA short description of the application. CommonMark syntax MAY be used for rich text representation.
+A short description of the application. [CommonMark] syntax MAY be used for rich text representation.
termsOfService
@@ -610,7 +674,7 @@ OpenAPI Specification v3.0.0
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
variables
@@ -730,7 +794,7 @@ OpenAPI Specification v3.0.0
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
@@ -1059,7 +1123,7 @@ OpenAPI Specification v3.0.0
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1220,7 +1284,7 @@ OpenAPI Specification v3.0.0
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1391,7 +1455,7 @@ OpenAPI Specification v3.0.0
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1446,7 +1510,7 @@ OpenAPI Specification v3.0.0
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1853,12 +1917,12 @@ OpenAPI Specification v3.0.0
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2357,7 +2421,7 @@ OpenAPI Specification v3.0.0
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2367,7 +2431,7 @@ OpenAPI Specification v3.0.0
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2611,7 +2675,7 @@ OpenAPI Specification v3.0.0
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2726,7 +2790,7 @@ OpenAPI Specification v3.0.0
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2825,7 +2889,7 @@ OpenAPI Specification v3.0.0
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source )
source = ( header-reference | query-reference | path-reference | body-reference )
@@ -2932,7 +2996,7 @@ OpenAPI Specification v3.0.0
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3064,8 +3128,8 @@ OpenAPI Specification v3.0.0
The Schema Object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
-This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation.
+This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation.
Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3097,7 +3161,7 @@ OpenAPI Specification v3.0.0
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
-description - CommonMark syntax MAY be used for rich text representation.
+description - [CommonMark] syntax MAY be used for rich text representation.
format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.
@@ -3957,7 +4021,7 @@ OpenAPI Specification v3.0.0
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
name
@@ -4309,7 +4373,19 @@ OpenAPI Specification v3.0.0
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4325,6 +4401,8 @@
OpenAPI Specification v3.0.0
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
-
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
+
- [RFC7159]
-
+ The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
-
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4333,6 +4411,8 @@
OpenAPI Specification v3.0.0
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.0.1
Copyright © 2017 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -259,7 +323,7 @@ OpenAPI Specification v3.0.1
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -267,7 +331,7 @@ OpenAPI Specification v3.0.1
SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 3.1.0 specification SHOULD be usable with tooling designed for 3.0.0.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -277,14 +341,14 @@ OpenAPI Specification v3.0.1
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
-- Tags MUST be limited to those allowed by the JSON Schema ruleset.
-- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
+- Tags MUST be limited to those allowed by the JSON Schema ruleset.
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
-An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.
Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00.
@@ -376,8 +440,8 @@
OpenAPI Specification v3.0.1
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
@@ -460,7 +524,7 @@ OpenAPI Specification v3.0.1
description
stringA short description of the application. CommonMark syntax MAY be used for rich text representation.
+A short description of the application. [CommonMark] syntax MAY be used for rich text representation.
termsOfService
@@ -615,7 +679,7 @@ OpenAPI Specification v3.0.1
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
variables
@@ -735,7 +799,7 @@ OpenAPI Specification v3.0.1
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
@@ -1064,7 +1128,7 @@ OpenAPI Specification v3.0.1
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1225,7 +1289,7 @@ OpenAPI Specification v3.0.1
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1396,7 +1460,7 @@ OpenAPI Specification v3.0.1
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1451,7 +1515,7 @@ OpenAPI Specification v3.0.1
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1858,12 +1922,12 @@ OpenAPI Specification v3.0.1
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2362,7 +2426,7 @@ OpenAPI Specification v3.0.1
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2372,7 +2436,7 @@ OpenAPI Specification v3.0.1
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2616,7 +2680,7 @@ OpenAPI Specification v3.0.1
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2731,7 +2795,7 @@ OpenAPI Specification v3.0.1
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2830,7 +2894,7 @@ OpenAPI Specification v3.0.1
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source )
source = ( header-reference | query-reference | path-reference | body-reference )
@@ -2937,7 +3001,7 @@ OpenAPI Specification v3.0.1
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3010,8 +3074,8 @@ OpenAPI Specification v3.0.1
The Schema Object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
-This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation.
+This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation.
Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3043,7 +3107,7 @@ OpenAPI Specification v3.0.1
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
-description - CommonMark syntax MAY be used for rich text representation.
+description - [CommonMark] syntax MAY be used for rich text representation.
format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.
@@ -3903,7 +3967,7 @@ OpenAPI Specification v3.0.1
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
name
@@ -4260,7 +4324,19 @@ OpenAPI Specification v3.0.1
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4276,6 +4352,8 @@
OpenAPI Specification v3.0.1
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
-
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
+
- [RFC7159]
-
+ The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
-
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4284,6 +4362,8 @@
OpenAPI Specification v3.0.1
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.0.2
Copyright © 2018 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -269,7 +333,7 @@ OpenAPI Specification v3.0.2
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -277,7 +341,7 @@ OpenAPI Specification v3.0.2
SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 3.1.0 specification SHOULD be usable with tooling designed for 3.0.0.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -288,14 +352,14 @@ OpenAPI Specification v3.0.2
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
-- Tags MUST be limited to those allowed by the JSON Schema ruleset.
-- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
+- Tags MUST be limited to those allowed by the JSON Schema ruleset.
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
-An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.
Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00.
@@ -375,8 +439,8 @@
OpenAPI Specification v3.0.2
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
@@ -459,7 +523,7 @@ OpenAPI Specification v3.0.2
description
stringA short description of the application. CommonMark syntax MAY be used for rich text representation.
+A short description of the application. [CommonMark] syntax MAY be used for rich text representation.
termsOfService
@@ -614,7 +678,7 @@ OpenAPI Specification v3.0.2
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
variables
@@ -734,7 +798,7 @@ OpenAPI Specification v3.0.2
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
@@ -1083,7 +1147,7 @@ OpenAPI Specification v3.0.2
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1244,7 +1308,7 @@ OpenAPI Specification v3.0.2
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1415,7 +1479,7 @@ OpenAPI Specification v3.0.2
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1470,7 +1534,7 @@ OpenAPI Specification v3.0.2
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1877,12 +1941,12 @@ OpenAPI Specification v3.0.2
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2381,7 +2445,7 @@ OpenAPI Specification v3.0.2
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2391,7 +2455,7 @@ OpenAPI Specification v3.0.2
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2635,7 +2699,7 @@ OpenAPI Specification v3.0.2
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2752,7 +2816,7 @@ OpenAPI Specification v3.0.2
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2851,7 +2915,7 @@ OpenAPI Specification v3.0.2
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source )
source = ( header-reference | query-reference | path-reference | body-reference )
@@ -2958,7 +3022,7 @@ OpenAPI Specification v3.0.2
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3031,8 +3095,8 @@ OpenAPI Specification v3.0.2
The Schema Object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
-This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation.
+This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation.
Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3064,7 +3128,7 @@ OpenAPI Specification v3.0.2
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. Consistent with JSON Schema, additionalProperties defaults to true.
-description - CommonMark syntax MAY be used for rich text representation.
+description - [CommonMark] syntax MAY be used for rich text representation.
format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.
@@ -3924,7 +3988,7 @@ OpenAPI Specification v3.0.2
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
name
@@ -4286,7 +4350,19 @@ OpenAPI Specification v3.0.2
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4302,6 +4378,8 @@
OpenAPI Specification v3.0.2
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
-
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
+
- [RFC7159]
-
+ The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
-
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4310,6 +4388,8 @@
OpenAPI Specification v3.0.2
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.0.3
Copyright © 2020 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -270,7 +334,7 @@ OpenAPI Specification v3.0.3
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -279,7 +343,7 @@ OpenAPI Specification v3.0.3
SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -290,7 +354,7 @@ OpenAPI Specification v3.0.3
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
@@ -377,8 +441,8 @@ OpenAPI Specification v3.0.3
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
@@ -461,7 +525,7 @@ OpenAPI Specification v3.0.3
description
stringA short description of the API. CommonMark syntax MAY be used for rich text representation.
+A short description of the API. [CommonMark] syntax MAY be used for rich text representation.
termsOfService
@@ -616,7 +680,7 @@ OpenAPI Specification v3.0.3
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
variables
@@ -736,7 +800,7 @@ OpenAPI Specification v3.0.3
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
@@ -1085,7 +1149,7 @@ OpenAPI Specification v3.0.3
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1246,7 +1310,7 @@ OpenAPI Specification v3.0.3
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1417,7 +1481,7 @@ OpenAPI Specification v3.0.3
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1472,7 +1536,7 @@ OpenAPI Specification v3.0.3
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1879,12 +1943,12 @@ OpenAPI Specification v3.0.3
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2382,7 +2446,7 @@ OpenAPI Specification v3.0.3
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2392,7 +2456,7 @@ OpenAPI Specification v3.0.3
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2652,7 +2716,7 @@ OpenAPI Specification v3.0.3
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2759,7 +2823,7 @@ OpenAPI Specification v3.0.3
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2858,7 +2922,7 @@ OpenAPI Specification v3.0.3
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
@@ -2972,7 +3036,7 @@ OpenAPI Specification v3.0.3
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3045,8 +3109,8 @@ OpenAPI Specification v3.0.3
The Schema Object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
-This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation.
+This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation.
Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3078,7 +3142,7 @@ OpenAPI Specification v3.0.3
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. Consistent with JSON Schema, additionalProperties defaults to true.
-description - CommonMark syntax MAY be used for rich text representation.
+description - [CommonMark] syntax MAY be used for rich text representation.
format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.
@@ -3938,7 +4002,7 @@ OpenAPI Specification v3.0.3
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
name
@@ -3956,7 +4020,7 @@ OpenAPI Specification v3.0.3
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
@@ -4327,7 +4391,21 @@ OpenAPI Specification v3.0.3
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-AUTHSCHEMES]
-
+ Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4353,6 +4431,8 @@
OpenAPI Specification v3.0.3
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.1.0
Copyright © 2021 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -271,14 +335,14 @@ OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
Occasionally, non-backwards compatible changes may be made in minor versions of the OAS where impact is believed to be low relative to the benefit provided.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the version of the OAS that it uses.
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -289,7 +353,7 @@ OpenAPI Specification v3.1.0
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
@@ -342,8 +406,8 @@ OpenAPI Specification v3.1.0
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
@@ -445,7 +509,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the API. CommonMark syntax MAY be used for rich text representation.
+A description of the API. [CommonMark] syntax MAY be used for rich text representation.
termsOfService
@@ -566,7 +630,7 @@ OpenAPI Specification v3.1.0
identifier
stringAn SPDX license expression for the API. The identifier field is mutually exclusive of the url field.
+An [SPDX] license expression for the API. The identifier field is mutually exclusive of the url field.
url
@@ -607,7 +671,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
variables
@@ -727,7 +791,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
@@ -1081,7 +1145,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1242,7 +1306,7 @@ OpenAPI Specification v3.1.0
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1414,7 +1478,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1469,7 +1533,7 @@ OpenAPI Specification v3.1.0
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1876,12 +1940,12 @@ OpenAPI Specification v3.1.0
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2382,7 +2446,7 @@ OpenAPI Specification v3.1.0
description
stringREQUIRED. A description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2392,7 +2456,7 @@ OpenAPI Specification v3.1.0
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2653,7 +2717,7 @@ OpenAPI Specification v3.1.0
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2760,7 +2824,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2859,7 +2923,7 @@ OpenAPI Specification v3.1.0
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
@@ -2973,7 +3037,7 @@ OpenAPI Specification v3.1.0
description
stringA description for the tag. CommonMark syntax MAY be used for rich text representation.
+A description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3021,7 +3085,7 @@ OpenAPI Specification v3.1.0
description
stringA description which by default SHOULD override that of the referenced component. CommonMark syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
+A description which by default SHOULD override that of the referenced component. [CommonMark] syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
@@ -3056,8 +3120,8 @@ OpenAPI Specification v3.1.0
stringOpenAPI Specification v3.1.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
stringhttpOpenAPI Specification v3.1.0
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-AUTHSCHEMES]
-
+ Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-2020-12]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00
+
- [JSON-Schema-Validation-2020-12]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2045]
-
Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2045
@@ -4344,6 +4422,10 @@
OpenAPI Specification v3.1.0
Returning Values from Forms: multipart/form-data. L. Masinter. IETF. July 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7578
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [SPDX]
-
+ SPDX License List. Linux Foundation. URL: https://spdx.org/licenses/
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
- [RFC1866]
-
+
- [ABNF]
- + Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234 +
- [CommonMark]
- + CommonMark Spec. URL: https://spec.commonmark.org/ +
- [CommonMark-0.27]
- + CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/ +
- [IANA-HTTP-AUTHSCHEMES]
- + Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/ +
- [IANA-HTTP-STATUS-CODES]
- + Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/ +
- [JSON-Schema-2020-12]
- + JSON Schema: A Media Type for Describing JSON Documents. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00 +
- [JSON-Schema-Validation-2020-12]
- + JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00 +
- [RFC1866]
- Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2045]
-
Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2045
@@ -4344,6 +4422,10 @@
OpenAPI Specification v3.1.0
Returning Values from Forms: multipart/form-data. L. Masinter. IETF. July 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7578
- [RFC8174]
- Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
- [SPDX]
- + SPDX License List. Linux Foundation. URL: https://spdx.org/licenses/ +
- [YAML]
- + YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v2.0
Version 2.0
@@ -213,13 +276,13 @@OpenAPI Specification v2.0
Copyright © 2014 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
-The Swagger specification is licensed under The Apache License, Version 2.0.
+The Swagger specification is licensed under The Apache License, Version 2.0.
Swagger™ is a project used to describe and document RESTful APIs.
The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.
@@ -274,10 +337,10 @@OpenAPI Specification v2.0
The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC7231] Section 6 and in the IANA Status Code Registry.
+The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC7231] Section 6 and in the IANA Status Code Registry.
The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to +
The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to represent a Swagger specification file.
For example, if a field is said to have an array value, the JSON array representation will be used:
@@ -289,7 +352,7 @@ OpenAPI Specification v2.0
All field names in the specification are case sensitive.
The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name.
The Swagger representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.
The Swagger representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.
By convention, the Swagger specification file is named swagger.json.
Primitive data types in the Swagger Specification are based on the types supported by the JSON-Schema Draft 4. Models are described using the Schema Object which is a subset of JSON Schema Draft 4.
@@ -1142,7 +1205,7 @@OpenAPI Specification v2.0
Query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
application/x-www-form-urlencoded, multipart/form-data or both are used as the content type of the request (in Swagger’s definition, the consumes property of an operation). This is the only parameter type that can be used to send files, thus supporting the file type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
+application/x-www-form-urlencoded, multipart/form-data or both are used as the content type of the request (in Swagger’s definition, the consumes property of an operation). This is the only parameter type that can be used to send files, thus supporting the file type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult [HTML401] Section 17.13.4:
application/x-www-form-urlencoded- Similar to the format of Query parameters but as a payload. For example,foo=1&bar=swagger- bothfooandbarare form parameters. This is normally used for simple parameters that are being transferred.multipart/form-data- each parameter takes a section in the payload with an internal header. For example, for the headerContent-Disposition: form-data; name="submit-name"the name of the parameter issubmit-name. This type of form parameters is more commonly used for file transfers.
@@ -2122,8 +2185,8 @@
OpenAPI Specification v2.0
$ref: 'definitions.yaml#/Pet'
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
-Further information about the properties can be found in JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here.
+The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
+Further information about the properties can be found in JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
- $ref - As a JSON Reference @@ -3309,7 +3372,15 @@
OpenAPI Specification v2.0
- [RFC2119]
-
+
- [HTML401]
- + HTML 4.01 Specification. Dave Raggett; Arnaud Le Hors; Ian Jacobs. W3C. 27 March 2018. W3C Recommendation. URL: https://www.w3.org/TR/html401/ +
- [IANA-HTTP-STATUS-CODES]
- + Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/ +
- [JSON-Schema-04]
- + JSON Schema: core definitions and terminology. Draft 4. Kris Zyp; Francis Galiegue; Gary Court. Internet Engineering Task Force (IETF). 31 January 2013. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04 +
- [JSON-Schema-Validation-04]
- + JSON Schema: interactive and non interactive validation. Draft 4. Kris Zyp; Francis Galiegue; Gary Court. Internet Engineering Task Force (IETF). 1 February 2013. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00 +
- [RFC2119]
- Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
- [RFC3339]
-
Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
@@ -3317,8 +3388,12 @@
OpenAPI Specification v2.0
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
- JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901 +
- [RFC7159]
- + The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7231]
- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html +
- [YAML]
- + YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.0.0
Copyright © 2017 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
-This document is licensed under The Apache License, Version 2.0.
+This document is licensed under The Apache License, Version 2.0.
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
@@ -254,15 +318,15 @@OpenAPI Specification v3.0.0
The HTTP Status Codes are used to indicate the status of the executed operation. -The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
+The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
The major.minor portion of the semver (for example 3.0) SHALL designate the OAS feature set. Typically, .patch versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.0.0 and 3.0.1 for example.
Subsequent minor version releases of the OpenAPI Specification (incrementing the minor version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 3.1.0 specification SHOULD be usable with tooling designed for 3.0.0.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -272,14 +336,14 @@ OpenAPI Specification v3.0.0
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
-- Tags MUST be limited to those allowed by the JSON Schema ruleset.
-- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
+- Tags MUST be limited to those allowed by the JSON Schema ruleset.
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.
Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00. @@ -371,8 +435,8 @@
OpenAPI Specification v3.0.0
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
OpenAPI Specification v3.0.0
openapi
stringREQUIRED. This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. The openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.
+REQUIRED. This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. The openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.
stringopenapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.OpenAPI Specification v3.0.0
description
stringA short description of the application. CommonMark syntax MAY be used for rich text representation.
+A short description of the application. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.0
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.0
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
stringstringOpenAPI Specification v3.0.0
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.0
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.0
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.0
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringstring, Media Type Object]OpenAPI Specification v3.0.0
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.0
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
string, Media Type Object]OpenAPI Specification v3.0.0
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.0
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.0
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source )
source = ( header-reference | query-reference | path-reference | body-reference )
@@ -2932,7 +2996,7 @@ OpenAPI Specification v3.0.0
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
OpenAPI Specification v3.0.0
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. -This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation. +This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3097,7 +3161,7 @@OpenAPI Specification v3.0.0
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
type is string, then default can be "foo" but cannot be 1.OpenAPI Specification v3.0.0
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.0
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4325,6 +4401,8 @@
OpenAPI Specification v3.0.0
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
-
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
+
- [RFC7159]
-
+ The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
-
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4333,6 +4411,8 @@
OpenAPI Specification v3.0.0
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
- [RFC1866]
-
+
- [ABNF]
- + Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234 +
- [CommonMark]
- + CommonMark Spec. URL: https://spec.commonmark.org/ +
- [CommonMark-0.27]
- + CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/ +
- [IANA-HTTP-STATUS-CODES]
- + Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/ +
- [JSON-Schema-05]
- + JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00 +
- [JSON-Schema-Validation-05]
- + JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00 +
- [RFC1866]
- Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4325,6 +4401,8 @@
OpenAPI Specification v3.0.0
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
- JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901 +
- [RFC7159]
- + The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
- Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4333,6 +4411,8 @@
OpenAPI Specification v3.0.0
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
- Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
- [YAML]
- + YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.0.1
Copyright © 2017 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -259,7 +323,7 @@ OpenAPI Specification v3.0.1
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -267,7 +331,7 @@ OpenAPI Specification v3.0.1
SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 3.1.0 specification SHOULD be usable with tooling designed for 3.0.0.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -277,14 +341,14 @@ OpenAPI Specification v3.0.1
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
-- Tags MUST be limited to those allowed by the JSON Schema ruleset.
-- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
+- Tags MUST be limited to those allowed by the JSON Schema ruleset.
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
-An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.
Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00.
@@ -376,8 +440,8 @@
OpenAPI Specification v3.0.1
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
@@ -460,7 +524,7 @@ OpenAPI Specification v3.0.1
description
stringA short description of the application. CommonMark syntax MAY be used for rich text representation.
+A short description of the application. [CommonMark] syntax MAY be used for rich text representation.
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.OpenAPI Specification v3.0.1
The HTTP Status Codes are used to indicate the status of the executed operation. -The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -267,7 +331,7 @@OpenAPI Specification v3.0.1
SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 3.1.0 specification SHOULD be usable with tooling designed for 3.0.0.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -277,14 +341,14 @@ OpenAPI Specification v3.0.1
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
-- Tags MUST be limited to those allowed by the JSON Schema ruleset.
-- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
+- Tags MUST be limited to those allowed by the JSON Schema ruleset.
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.
Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00. @@ -376,8 +440,8 @@
OpenAPI Specification v3.0.1
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
OpenAPI Specification v3.0.1
description
stringA short description of the application. CommonMark syntax MAY be used for rich text representation.
+A short description of the application. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.1
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.1
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.1
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1225,7 +1289,7 @@ OpenAPI Specification v3.0.1
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1396,7 +1460,7 @@ OpenAPI Specification v3.0.1
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1451,7 +1515,7 @@ OpenAPI Specification v3.0.1
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1858,12 +1922,12 @@ OpenAPI Specification v3.0.1
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2362,7 +2426,7 @@ OpenAPI Specification v3.0.1
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2372,7 +2436,7 @@ OpenAPI Specification v3.0.1
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2616,7 +2680,7 @@ OpenAPI Specification v3.0.1
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2731,7 +2795,7 @@ OpenAPI Specification v3.0.1
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2830,7 +2894,7 @@ OpenAPI Specification v3.0.1
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source )
source = ( header-reference | query-reference | path-reference | body-reference )
@@ -2937,7 +3001,7 @@ OpenAPI Specification v3.0.1
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3010,8 +3074,8 @@ OpenAPI Specification v3.0.1
The Schema Object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
-This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation.
+This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation.
Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3043,7 +3107,7 @@ OpenAPI Specification v3.0.1
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
-description - CommonMark syntax MAY be used for rich text representation.
+description - [CommonMark] syntax MAY be used for rich text representation.
format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.
@@ -3903,7 +3967,7 @@ OpenAPI Specification v3.0.1
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
name
@@ -4260,7 +4324,19 @@ OpenAPI Specification v3.0.1
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4276,6 +4352,8 @@
OpenAPI Specification v3.0.1
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
-
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
+
- [RFC7159]
-
+ The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
-
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4284,6 +4362,8 @@
OpenAPI Specification v3.0.1
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.0.2
Copyright © 2018 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -269,7 +333,7 @@ OpenAPI Specification v3.0.2
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -277,7 +341,7 @@ OpenAPI Specification v3.0.2
SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 3.1.0 specification SHOULD be usable with tooling designed for 3.0.0.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -288,14 +352,14 @@ OpenAPI Specification v3.0.2
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
-- Tags MUST be limited to those allowed by the JSON Schema ruleset.
-- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
+- Tags MUST be limited to those allowed by the JSON Schema ruleset.
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
-An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.
Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00.
@@ -375,8 +439,8 @@
OpenAPI Specification v3.0.2
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
@@ -459,7 +523,7 @@ OpenAPI Specification v3.0.2
description
stringA short description of the application. CommonMark syntax MAY be used for rich text representation.
+A short description of the application. [CommonMark] syntax MAY be used for rich text representation.
termsOfService
@@ -614,7 +678,7 @@ OpenAPI Specification v3.0.2
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
variables
@@ -734,7 +798,7 @@ OpenAPI Specification v3.0.2
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
@@ -1083,7 +1147,7 @@ OpenAPI Specification v3.0.2
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1244,7 +1308,7 @@ OpenAPI Specification v3.0.2
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1415,7 +1479,7 @@ OpenAPI Specification v3.0.2
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1470,7 +1534,7 @@ OpenAPI Specification v3.0.2
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1877,12 +1941,12 @@ OpenAPI Specification v3.0.2
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2381,7 +2445,7 @@ OpenAPI Specification v3.0.2
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2391,7 +2455,7 @@ OpenAPI Specification v3.0.2
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2635,7 +2699,7 @@ OpenAPI Specification v3.0.2
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2752,7 +2816,7 @@ OpenAPI Specification v3.0.2
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2851,7 +2915,7 @@ OpenAPI Specification v3.0.2
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source )
source = ( header-reference | query-reference | path-reference | body-reference )
@@ -2958,7 +3022,7 @@ OpenAPI Specification v3.0.2
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3031,8 +3095,8 @@ OpenAPI Specification v3.0.2
The Schema Object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
-This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation.
+This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation.
Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3064,7 +3128,7 @@ OpenAPI Specification v3.0.2
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. Consistent with JSON Schema, additionalProperties defaults to true.
-description - CommonMark syntax MAY be used for rich text representation.
+description - [CommonMark] syntax MAY be used for rich text representation.
format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.
@@ -3924,7 +3988,7 @@ OpenAPI Specification v3.0.2
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
name
@@ -4286,7 +4350,19 @@ OpenAPI Specification v3.0.2
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4302,6 +4378,8 @@
OpenAPI Specification v3.0.2
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
-
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
+
- [RFC7159]
-
+ The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
-
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4310,6 +4388,8 @@
OpenAPI Specification v3.0.2
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.0.3
Copyright © 2020 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -270,7 +334,7 @@ OpenAPI Specification v3.0.3
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -279,7 +343,7 @@ OpenAPI Specification v3.0.3
SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -290,7 +354,7 @@ OpenAPI Specification v3.0.3
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
@@ -377,8 +441,8 @@ OpenAPI Specification v3.0.3
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
@@ -461,7 +525,7 @@ OpenAPI Specification v3.0.3
description
stringA short description of the API. CommonMark syntax MAY be used for rich text representation.
+A short description of the API. [CommonMark] syntax MAY be used for rich text representation.
termsOfService
@@ -616,7 +680,7 @@ OpenAPI Specification v3.0.3
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
variables
@@ -736,7 +800,7 @@ OpenAPI Specification v3.0.3
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
@@ -1085,7 +1149,7 @@ OpenAPI Specification v3.0.3
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1246,7 +1310,7 @@ OpenAPI Specification v3.0.3
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1417,7 +1481,7 @@ OpenAPI Specification v3.0.3
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1472,7 +1536,7 @@ OpenAPI Specification v3.0.3
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1879,12 +1943,12 @@ OpenAPI Specification v3.0.3
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2382,7 +2446,7 @@ OpenAPI Specification v3.0.3
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2392,7 +2456,7 @@ OpenAPI Specification v3.0.3
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2652,7 +2716,7 @@ OpenAPI Specification v3.0.3
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2759,7 +2823,7 @@ OpenAPI Specification v3.0.3
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2858,7 +2922,7 @@ OpenAPI Specification v3.0.3
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
@@ -2972,7 +3036,7 @@ OpenAPI Specification v3.0.3
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3045,8 +3109,8 @@ OpenAPI Specification v3.0.3
The Schema Object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
-This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation.
+This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation.
Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3078,7 +3142,7 @@ OpenAPI Specification v3.0.3
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. Consistent with JSON Schema, additionalProperties defaults to true.
-description - CommonMark syntax MAY be used for rich text representation.
+description - [CommonMark] syntax MAY be used for rich text representation.
format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.
@@ -3938,7 +4002,7 @@ OpenAPI Specification v3.0.3
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
name
@@ -3956,7 +4020,7 @@ OpenAPI Specification v3.0.3
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
@@ -4327,7 +4391,21 @@ OpenAPI Specification v3.0.3
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-AUTHSCHEMES]
-
+ Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4353,6 +4431,8 @@
OpenAPI Specification v3.0.3
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.1.0
Copyright © 2021 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -271,14 +335,14 @@ OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
Occasionally, non-backwards compatible changes may be made in minor versions of the OAS where impact is believed to be low relative to the benefit provided.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the version of the OAS that it uses.
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -289,7 +353,7 @@ OpenAPI Specification v3.1.0
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
@@ -342,8 +406,8 @@ OpenAPI Specification v3.1.0
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
@@ -445,7 +509,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the API. CommonMark syntax MAY be used for rich text representation.
+A description of the API. [CommonMark] syntax MAY be used for rich text representation.
termsOfService
@@ -566,7 +630,7 @@ OpenAPI Specification v3.1.0
identifier
stringAn SPDX license expression for the API. The identifier field is mutually exclusive of the url field.
+An [SPDX] license expression for the API. The identifier field is mutually exclusive of the url field.
url
@@ -607,7 +671,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
variables
@@ -727,7 +791,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
@@ -1081,7 +1145,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1242,7 +1306,7 @@ OpenAPI Specification v3.1.0
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1414,7 +1478,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1469,7 +1533,7 @@ OpenAPI Specification v3.1.0
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1876,12 +1940,12 @@ OpenAPI Specification v3.1.0
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2382,7 +2446,7 @@ OpenAPI Specification v3.1.0
description
stringREQUIRED. A description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2392,7 +2456,7 @@ OpenAPI Specification v3.1.0
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2653,7 +2717,7 @@ OpenAPI Specification v3.1.0
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2760,7 +2824,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2859,7 +2923,7 @@ OpenAPI Specification v3.1.0
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
@@ -2973,7 +3037,7 @@ OpenAPI Specification v3.1.0
description
stringA description for the tag. CommonMark syntax MAY be used for rich text representation.
+A description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3021,7 +3085,7 @@ OpenAPI Specification v3.1.0
description
stringA description which by default SHOULD override that of the referenced component. CommonMark syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
+A description which by default SHOULD override that of the referenced component. [CommonMark] syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
@@ -3056,8 +3120,8 @@ OpenAPI Specification v3.1.0
stringOpenAPI Specification v3.0.1
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.1
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.1
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.1
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringstring, Media Type Object]OpenAPI Specification v3.0.1
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.1
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
string, Media Type Object]OpenAPI Specification v3.0.1
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.1
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.1
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source )
source = ( header-reference | query-reference | path-reference | body-reference )
@@ -2937,7 +3001,7 @@ OpenAPI Specification v3.0.1
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
OpenAPI Specification v3.0.1
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. -This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation. +This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3043,7 +3107,7 @@OpenAPI Specification v3.0.1
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
type is string, then default can be "foo" but cannot be 1.OpenAPI Specification v3.0.1
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.1
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4276,6 +4352,8 @@
OpenAPI Specification v3.0.1
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
-
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
+
- [RFC7159]
-
+ The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
-
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4284,6 +4362,8 @@
OpenAPI Specification v3.0.1
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
- [RFC1866]
-
+
- [ABNF]
- + Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234 +
- [CommonMark]
- + CommonMark Spec. URL: https://spec.commonmark.org/ +
- [CommonMark-0.27]
- + CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/ +
- [IANA-HTTP-STATUS-CODES]
- + Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/ +
- [JSON-Schema-05]
- + JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00 +
- [JSON-Schema-Validation-05]
- + JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00 +
- [RFC1866]
- Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4276,6 +4352,8 @@
OpenAPI Specification v3.0.1
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
- JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901 +
- [RFC7159]
- + The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
- Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4284,6 +4362,8 @@
OpenAPI Specification v3.0.1
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
- Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
- [YAML]
- + YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.0.2
Copyright © 2018 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -269,7 +333,7 @@ OpenAPI Specification v3.0.2
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -277,7 +341,7 @@ OpenAPI Specification v3.0.2
SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 3.1.0 specification SHOULD be usable with tooling designed for 3.0.0.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -288,14 +352,14 @@ OpenAPI Specification v3.0.2
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
-- Tags MUST be limited to those allowed by the JSON Schema ruleset.
-- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
+- Tags MUST be limited to those allowed by the JSON Schema ruleset.
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
-An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.
Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00.
@@ -375,8 +439,8 @@
OpenAPI Specification v3.0.2
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
@@ -459,7 +523,7 @@ OpenAPI Specification v3.0.2
description
stringA short description of the application. CommonMark syntax MAY be used for rich text representation.
+A short description of the application. [CommonMark] syntax MAY be used for rich text representation.
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.OpenAPI Specification v3.0.2
The HTTP Status Codes are used to indicate the status of the executed operation. -The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -277,7 +341,7 @@OpenAPI Specification v3.0.2
SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 3.1.0 specification SHOULD be usable with tooling designed for 3.0.0.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -288,14 +352,14 @@ OpenAPI Specification v3.0.2
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
-- Tags MUST be limited to those allowed by the JSON Schema ruleset.
-- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
+- Tags MUST be limited to those allowed by the JSON Schema ruleset.
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, $ref fields MUST be used in the specification to reference those parts as follows from the JSON Schema definitions.
It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.
Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00. @@ -375,8 +439,8 @@
OpenAPI Specification v3.0.2
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
OpenAPI Specification v3.0.2
description
stringA short description of the application. CommonMark syntax MAY be used for rich text representation.
+A short description of the application. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.2
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.2
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
stringstringOpenAPI Specification v3.0.2
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.2
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.2
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.2
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringstring, Media Type Object]OpenAPI Specification v3.0.2
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.2
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
string, Media Type Object]OpenAPI Specification v3.0.2
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.2
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.2
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source )
source = ( header-reference | query-reference | path-reference | body-reference )
@@ -2958,7 +3022,7 @@ OpenAPI Specification v3.0.2
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
OpenAPI Specification v3.0.2
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. -This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation. +This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3064,7 +3128,7 @@OpenAPI Specification v3.0.2
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
additionalProperties defaults to true.type is string, then default can be "foo" but cannot be 1.OpenAPI Specification v3.0.2
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.2
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4302,6 +4378,8 @@
OpenAPI Specification v3.0.2
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
-
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
+
- [RFC7159]
-
+ The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
-
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4310,6 +4388,8 @@
OpenAPI Specification v3.0.2
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
- [RFC1866]
-
+
- [ABNF]
- + Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234 +
- [CommonMark]
- + CommonMark Spec. URL: https://spec.commonmark.org/ +
- [CommonMark-0.27]
- + CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/ +
- [IANA-HTTP-STATUS-CODES]
- + Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/ +
- [JSON-Schema-05]
- + JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00 +
- [JSON-Schema-Validation-05]
- + JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00 +
- [RFC1866]
- Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4302,6 +4378,8 @@
OpenAPI Specification v3.0.2
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
- [RFC6901]
- JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901 +
- [RFC7159]
- + The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
- [RFC7230]
- Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
- [RFC7231]
-
@@ -4310,6 +4388,8 @@
OpenAPI Specification v3.0.2
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
- Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
- [YAML]
- + YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.0.3
Copyright © 2020 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -270,7 +334,7 @@ OpenAPI Specification v3.0.3
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -279,7 +343,7 @@ OpenAPI Specification v3.0.3
SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -290,7 +354,7 @@ OpenAPI Specification v3.0.3
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
@@ -377,8 +441,8 @@ OpenAPI Specification v3.0.3
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
@@ -461,7 +525,7 @@ OpenAPI Specification v3.0.3
description
stringA short description of the API. CommonMark syntax MAY be used for rich text representation.
+A short description of the API. [CommonMark] syntax MAY be used for rich text representation.
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.OpenAPI Specification v3.0.3
The HTTP Status Codes are used to indicate the status of the executed operation. -The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -279,7 +343,7 @@OpenAPI Specification v3.0.3
SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named swagger and value "2.0".)
An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -290,7 +354,7 @@ OpenAPI Specification v3.0.3
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
@@ -377,8 +441,8 @@ OpenAPI Specification v3.0.3
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
OpenAPI Specification v3.0.3
description
stringA short description of the API. CommonMark syntax MAY be used for rich text representation.
+A short description of the API. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.3
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.3
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.3
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1246,7 +1310,7 @@ OpenAPI Specification v3.0.3
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1417,7 +1481,7 @@ OpenAPI Specification v3.0.3
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1472,7 +1536,7 @@ OpenAPI Specification v3.0.3
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1879,12 +1943,12 @@ OpenAPI Specification v3.0.3
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2382,7 +2446,7 @@ OpenAPI Specification v3.0.3
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2392,7 +2456,7 @@ OpenAPI Specification v3.0.3
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2652,7 +2716,7 @@ OpenAPI Specification v3.0.3
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2759,7 +2823,7 @@ OpenAPI Specification v3.0.3
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2858,7 +2922,7 @@ OpenAPI Specification v3.0.3
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
@@ -2972,7 +3036,7 @@ OpenAPI Specification v3.0.3
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3045,8 +3109,8 @@ OpenAPI Specification v3.0.3
The Schema Object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays.
-This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation.
+This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation.
Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3078,7 +3142,7 @@ OpenAPI Specification v3.0.3
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. Consistent with JSON Schema, additionalProperties defaults to true.
-description - CommonMark syntax MAY be used for rich text representation.
+description - [CommonMark] syntax MAY be used for rich text representation.
format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.
@@ -3938,7 +4002,7 @@ OpenAPI Specification v3.0.3
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
name
@@ -3956,7 +4020,7 @@ OpenAPI Specification v3.0.3
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
@@ -4327,7 +4391,21 @@ OpenAPI Specification v3.0.3
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-AUTHSCHEMES]
-
+ Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4353,6 +4431,8 @@
OpenAPI Specification v3.0.3
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.1.0
Copyright © 2021 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -271,14 +335,14 @@ OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
Occasionally, non-backwards compatible changes may be made in minor versions of the OAS where impact is believed to be low relative to the benefit provided.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the version of the OAS that it uses.
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -289,7 +353,7 @@ OpenAPI Specification v3.1.0
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
@@ -342,8 +406,8 @@ OpenAPI Specification v3.1.0
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
@@ -445,7 +509,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the API. CommonMark syntax MAY be used for rich text representation.
+A description of the API. [CommonMark] syntax MAY be used for rich text representation.
termsOfService
@@ -566,7 +630,7 @@ OpenAPI Specification v3.1.0
identifier
stringAn SPDX license expression for the API. The identifier field is mutually exclusive of the url field.
+An [SPDX] license expression for the API. The identifier field is mutually exclusive of the url field.
url
@@ -607,7 +671,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
variables
@@ -727,7 +791,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
@@ -1081,7 +1145,7 @@ OpenAPI Specification v3.1.0
description
stringAn optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.
+An optional, string description, intended to apply to all operations in this path. [CommonMark] syntax MAY be used for rich text representation.
get
@@ -1242,7 +1306,7 @@ OpenAPI Specification v3.1.0
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -1414,7 +1478,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
url
@@ -1469,7 +1533,7 @@ OpenAPI Specification v3.1.0
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
required
@@ -1876,12 +1940,12 @@ OpenAPI Specification v3.1.0
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
content
Map[string, Media Type Object]
-REQUIRED. The content of the request body. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+REQUIRED. The content of the request body. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
required
@@ -2382,7 +2446,7 @@ OpenAPI Specification v3.1.0
description
stringREQUIRED. A description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A description of the response. [CommonMark] syntax MAY be used for rich text representation.
headers
@@ -2392,7 +2456,7 @@ OpenAPI Specification v3.1.0
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
links
@@ -2653,7 +2717,7 @@ OpenAPI Specification v3.1.0
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
value
@@ -2760,7 +2824,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
server
@@ -2859,7 +2923,7 @@ OpenAPI Specification v3.1.0
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
@@ -2973,7 +3037,7 @@ OpenAPI Specification v3.1.0
description
stringA description for the tag. CommonMark syntax MAY be used for rich text representation.
+A description for the tag. [CommonMark] syntax MAY be used for rich text representation.
externalDocs
@@ -3021,7 +3085,7 @@ OpenAPI Specification v3.1.0
description
stringA description which by default SHOULD override that of the referenced component. CommonMark syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
+A description which by default SHOULD override that of the referenced component. [CommonMark] syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
@@ -3056,8 +3120,8 @@ OpenAPI Specification v3.1.0
stringOpenAPI Specification v3.0.3
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.3
description
stringA short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A short description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.3
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.3
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringstring, Media Type Object]OpenAPI Specification v3.0.3
description
stringREQUIRED. A short description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A short description of the response. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.3
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
string, Media Type Object]OpenAPI Specification v3.0.3
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.3
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.3
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
@@ -2972,7 +3036,7 @@ OpenAPI Specification v3.0.3
description
stringA short description for the tag. CommonMark syntax MAY be used for rich text representation.
+A short description for the tag. [CommonMark] syntax MAY be used for rich text representation.
OpenAPI Specification v3.0.3
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. -This object is an extended subset of the JSON Schema Specification Wright Draft 00.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation. +This object is an extended subset of the JSON Schema Specification Wright Draft 00.
+For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -3078,7 +3142,7 @@OpenAPI Specification v3.0.3
MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
additionalProperties defaults to true.type is string, then default can be "foo" but cannot be 1.OpenAPI Specification v3.0.3
description
stringAny
-A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A short description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.0.3
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
stringhttpOpenAPI Specification v3.0.3
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-AUTHSCHEMES]
-
+ Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-05]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00
+
- [JSON-Schema-Validation-05]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4353,6 +4431,8 @@
OpenAPI Specification v3.0.3
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
- [RFC1866]
-
+
- [ABNF]
- + Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234 +
- [CommonMark]
- + CommonMark Spec. URL: https://spec.commonmark.org/ +
- [CommonMark-0.27]
- + CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/ +
- [IANA-HTTP-AUTHSCHEMES]
- + Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/ +
- [IANA-HTTP-STATUS-CODES]
- + Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/ +
- [JSON-Schema-05]
- + JSON Schema: A Media Type for Describing JSON Documents. Draft 5. Austin Wright. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00 +
- [JSON-Schema-Validation-05]
- + JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 5. Austin Wright; G. Luff. Internet Engineering Task Force (IETF). 13 October 2016. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00 +
- [RFC1866]
- Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2119]
-
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
@@ -4353,6 +4431,8 @@
OpenAPI Specification v3.0.3
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7235.html
- [RFC8174]
- Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
- [YAML]
- + YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
OpenAPI Specification v3.1.0
Copyright © 2021 the Linux Foundation
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.
@@ -271,14 +335,14 @@ OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
Occasionally, non-backwards compatible changes may be made in minor versions of the OAS where impact is believed to be low relative to the benefit provided.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the version of the OAS that it uses.
-An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -289,7 +353,7 @@ OpenAPI Specification v3.1.0
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
@@ -342,8 +406,8 @@ OpenAPI Specification v3.1.0
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
@@ -445,7 +509,7 @@ OpenAPI Specification v3.1.0
description
stringA description of the API. CommonMark syntax MAY be used for rich text representation.
+A description of the API. [CommonMark] syntax MAY be used for rich text representation.
What is the OpenAPI Specification?
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.Status of This Document
The source-of-truth for the specification is the GitHub markdown file referenced above.OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation. -The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
Occasionally, non-backwards compatible changes may be made in minor versions of the OAS where impact is believed to be low relative to the benefit provided.
An OpenAPI document compatible with OAS 3.*.* contains a required openapi field which designates the version of the OAS that it uses.
An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
For example, if a field has an array value, the JSON array representation will be used:
{
@@ -289,7 +353,7 @@ OpenAPI Specification v3.1.0
MUST have unique names within the containing object.
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:
- Tags MUST be limited to those allowed by the JSON Schema ruleset.
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
@@ -342,8 +406,8 @@ OpenAPI Specification v3.1.0
-
Throughout the specification description fields are noted as supporting CommonMark markdown formatting.
-Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
+Throughout the specification description fields are noted as supporting [CommonMark] markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark-0.27]. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
OpenAPI Specification v3.1.0
description
stringA description of the API. CommonMark syntax MAY be used for rich text representation.
+A description of the API. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
identifier
stringAn SPDX license expression for the API. The identifier field is mutually exclusive of the url field.
+An [SPDX] license expression for the API. The identifier field is mutually exclusive of the url field.
stringidentifier field is mutually exclusive of the url field.identifier field is mutually exclusive of the url field.OpenAPI Specification v3.1.0
description
stringAn optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+An optional string describing the host designated by the URL. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
description
stringAn optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+An optional description for the server variable. [CommonMark] syntax MAY be used for rich text representation.
stringstringOpenAPI Specification v3.1.0
description
stringA verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
+A verbose explanation of the operation behavior. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
description
stringA description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+A description of the target documentation. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
description
stringA brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the parameter. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
description
stringA brief description of the request body. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+A brief description of the request body. This could contain examples of use. [CommonMark] syntax MAY be used for rich text representation.
stringstring, Media Type Object]OpenAPI Specification v3.1.0
description
stringREQUIRED. A description of the response. CommonMark syntax MAY be used for rich text representation.
+REQUIRED. A description of the response. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
content
Map[string, Media Type Object]
-A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+A map containing descriptions of potential response payloads. The key is a media type or media type range, see [RFC7231] Appendix D, and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
string, Media Type Object]OpenAPI Specification v3.1.0
description
stringLong description for the example. CommonMark syntax MAY be used for rich text representation.
+Long description for the example. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
description
stringA description of the link. CommonMark syntax MAY be used for rich text representation.
+A description of the link. [CommonMark] syntax MAY be used for rich text representation.
stringOpenAPI Specification v3.1.0
Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link Objects and Callback Objects.
-The runtime expression is defined by the following ABNF syntax
+The runtime expression is defined by the following [ABNF] syntax
expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
source = ( header-reference / query-reference / path-reference / body-reference )
@@ -2973,7 +3037,7 @@ OpenAPI Specification v3.1.0
description
stringA description for the tag. CommonMark syntax MAY be used for rich text representation.
+A description for the tag. [CommonMark] syntax MAY be used for rich text representation.
OpenAPI Specification v3.1.0
description
stringA description which by default SHOULD override that of the referenced component. CommonMark syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
+A description which by default SHOULD override that of the referenced component. [CommonMark] syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
stringdescription field, then this field has no effect.description field, then this field has no effect.OpenAPI Specification v3.1.0
The Schema Object allows the definition of input and output data types. -These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 2020-12.
-For more information about the properties, see JSON Schema Core and JSON Schema Validation.
+These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 2020-12. +For more information about the properties, see JSON Schema Core and JSON Schema Validation.
Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics. Where JSON Schema indicates that behavior is defined by the application (e.g. for annotations), OAS also defers the definition of semantics to the application consuming the OpenAPI document.
OpenAPI Specification v3.1.0
“OAS dialect schema id”).
The following properties are taken from the JSON Schema specification but their definitions have been extended by the OAS:
-
-
- description - CommonMark syntax MAY be used for rich text representation. +
- description - [CommonMark] syntax MAY be used for rich text representation.
- format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
In addition to the JSON Schema properties comprising the OAS dialect, the Schema Object supports keywords from any other vocabularies, or entirely arbitrary properties.
@@ -3910,7 +3974,7 @@OpenAPI Specification v3.1.0
description
stringAny
-A description for security scheme. CommonMark syntax MAY be used for rich text representation.
+A description for security scheme. [CommonMark] syntax MAY be used for rich text representation.
name
@@ -3928,7 +3992,7 @@ OpenAPI Specification v3.1.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
@@ -4314,7 +4378,21 @@ OpenAPI Specification v3.1.0
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-AUTHSCHEMES]
-
+ Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-2020-12]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00
+
- [JSON-Schema-Validation-2020-12]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2045]
-
Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2045
@@ -4344,6 +4422,10 @@
OpenAPI Specification v3.1.0
Returning Values from Forms: multipart/form-data. L. Masinter. IETF. July 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7578
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [SPDX]
-
+ SPDX License List. Linux Foundation. URL: https://spdx.org/licenses/
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
stringOpenAPI Specification v3.1.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
stringhttpOpenAPI Specification v3.1.0
- - [RFC1866]
-
+
- [ABNF]
-
+ Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234
+
- [CommonMark]
-
+ CommonMark Spec. URL: https://spec.commonmark.org/
+
- [CommonMark-0.27]
-
+ CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/
+
- [IANA-HTTP-AUTHSCHEMES]
-
+ Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/
+
- [IANA-HTTP-STATUS-CODES]
-
+ Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/
+
- [JSON-Schema-2020-12]
-
+ JSON Schema: A Media Type for Describing JSON Documents. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00
+
- [JSON-Schema-Validation-2020-12]
-
+ JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00
+
- [RFC1866]
-
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2045]
-
Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2045
@@ -4344,6 +4422,10 @@
OpenAPI Specification v3.1.0
Returning Values from Forms: multipart/form-data. L. Masinter. IETF. July 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7578
- [RFC8174]
-
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
+
- [SPDX]
-
+ SPDX License List. Linux Foundation. URL: https://spdx.org/licenses/
+
- [YAML]
-
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
- [RFC1866]
-
+
- [ABNF]
- + Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234 +
- [CommonMark]
- + CommonMark Spec. URL: https://spec.commonmark.org/ +
- [CommonMark-0.27]
- + CommonMark Spec, Version 0.27. John MacFarlane. 18 November 2016. URL: https://spec.commonmark.org/0.27/ +
- [IANA-HTTP-AUTHSCHEMES]
- + Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry. IANA. URL: https://www.iana.org/assignments/http-authschemes/ +
- [IANA-HTTP-STATUS-CODES]
- + Hypertext Transfer Protocol (HTTP) Status Code Registry. IANA. URL: https://www.iana.org/assignments/http-status-codes/ +
- [JSON-Schema-2020-12]
- + JSON Schema: A Media Type for Describing JSON Documents. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00 +
- [JSON-Schema-Validation-2020-12]
- + JSON Schema Validation: A Vocabulary for Structural Validation of JSON. Draft 2020-12. Austin Wright; Henry Andrews; Ben Hutton. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00 +
- [RFC1866]
- Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
- [RFC2045]
-
Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2045
@@ -4344,6 +4422,10 @@
OpenAPI Specification v3.1.0
Returning Values from Forms: multipart/form-data. L. Masinter. IETF. July 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7578
- [RFC8174]
- Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
- [SPDX]
- + SPDX License List. Linux Foundation. URL: https://spdx.org/licenses/ +
- [YAML]
- + YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html