Skip to content

Commit

Permalink
Settle on "OpenAPI Description" (3.0.4) (#3384)
Browse files Browse the repository at this point in the history
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"
  • Loading branch information
handrews authored Sep 28, 2023
1 parent def7270 commit 8397a89
Showing 1 changed file with 7 additions and 7 deletions.
14 changes: 7 additions & 7 deletions versions/3.0.4.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,14 @@ An OpenAPI definition can then be used by documentation generation tools to disp
<!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->

- [Definitions](#definitions)
- [OpenAPI Document](#oasDocument)
- [OpenAPI Description](#oasDocument)
- [Path Templating](#pathTemplating)
- [Media Types](#mediaTypes)
- [HTTP Status Codes](#httpCodes)
- [Specification](#specification)
- [Versions](#versions)
- [Format](#format)
- [Document Structure](#documentStructure)
- [OpenAPI Description Structure](#documentStructure)
- [Data Types](#dataTypes)
- [Rich Text Formatting](#richText)
- [Relative References In URLs](#relativeReferences)
Expand Down Expand Up @@ -67,8 +67,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp

## Definitions

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

##### <a name="pathTemplating"></a>Path Templating
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.
Expand Down Expand Up @@ -135,11 +135,11 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA

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

### <a name="documentStructure"></a>Document Structure
### <a name="documentStructure"></a>OpenAPI Description Structure

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.
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 **entry OpenAPI document.**

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

### <a name="dataTypes"></a>Data Types

Expand Down

0 comments on commit 8397a89

Please sign in to comment.