Skip to content

Settle on "OpenAPI Description" (3.1.1) #3385

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 28, 2023
Merged

Settle on "OpenAPI Description" (3.1.1) #3385

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions versions/3.1.1.md
View file
Open in desktop
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 URIs](#relativeReferencesURI)
Expand Down Expand Up @@ -68,8 +68,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp

## Definitions

##### <a name="oasDocument"></a>OpenAPI Document
A self-contained or composite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI document 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, and MUST contain at least one [paths](#pathsObject) field, [components](#oasComponents) field, or [webhooks](#oasWebhooks) field.

##### <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 @@ -134,11 +134,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 author. In the latter case, [`Reference Objects`](#referenceObject) and [`Schema Object`](#schemaObject) `$ref` keywords are used.
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, [`Reference Objects`](#referenceObject) and [`Schema Object`](#schemaObject) `$ref` keywords are used. 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