Skip to content

Commit 9cb90a2

Browse files
committed
Settle on "OpenAPI Description" (3.0.4)
This follows up from a discussion on the OAI slack that decided: * redefining "document" to sometimes mean multiple documents is confusing * "description" has more support than "definition"
1 parent def7270 commit 9cb90a2

File tree

1 file changed

+6
-6
lines changed

1 file changed

+6
-6
lines changed

versions/3.0.4.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,14 @@ An OpenAPI definition can then be used by documentation generation tools to disp
1616
<!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->
1717

1818
- [Definitions](#definitions)
19-
- [OpenAPI Document](#oasDocument)
19+
- [OpenAPI Description](#oasDocument)
2020
- [Path Templating](#pathTemplating)
2121
- [Media Types](#mediaTypes)
2222
- [HTTP Status Codes](#httpCodes)
2323
- [Specification](#specification)
2424
- [Versions](#versions)
2525
- [Format](#format)
26-
- [Document Structure](#documentStructure)
26+
- [OpenAPI Description Structure](#documentStructure)
2727
- [Data Types](#dataTypes)
2828
- [Rich Text Formatting](#richText)
2929
- [Relative References In URLs](#relativeReferences)
@@ -67,8 +67,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp
6767

6868
## Definitions
6969

70-
##### <a name="oasDocument"></a>OpenAPI Document
71-
A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
70+
##### <a name="oasDocument"></a>OpenAPI Description
71+
A document (or set of documents) that describes an API. An OpenAPI Description (OAD) uses and conforms to the OpenAPI Specification.
7272

7373
##### <a name="pathTemplating"></a>Path Templating
7474
Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
@@ -135,9 +135,9 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
135135

136136
**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.
137137

138-
### <a name="documentStructure"></a>Document Structure
138+
### <a name="documentStructure"></a>OpenAPI Description Structure
139139

140-
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](https://json-schema.org) definitions.
140+
An OpenAPI Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](https://json-schema.org) definitions. In a multi-document description, the document containing the [OpenAPI Object](#oasObject) is known as the **root OpenAPI document.**
141141

142142
It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`.
143143

0 commit comments

Comments
 (0)