Skip to content

revise docs for v3.1 #26

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 2 commits into from
Aug 27, 2021
Merged

revise docs for v3.1 #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cdb66ef
"paths" is no longer mandatory
karenetheridge Aug 22, 2021
3a7776a
/paths/responses is no longer mandatory
karenetheridge Aug 22, 2021
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
2 changes: 1 addition & 1 deletion specification-paths.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ paths:

## The Operation Object

Besides giving the operation a `summary` and a `description`, the [Operation Object](https://spec.openapis.org/oas/v3.1.0#operationObject) basically describes the operation's parameters, payload and possible server responses. The rest of this page explains the `responses` field (which is **mandatory**) whereas parameters and payload are dealt with in [another page](specification-parameters.md).
Besides giving the operation a `summary` and a `description`, the [Operation Object](https://spec.openapis.org/oas/v3.1.0#operationObject) basically describes the operation's parameters, payload and possible server responses. The rest of this page explains the `responses` field, whereas parameters and payload are dealt with in [another page](specification-parameters.md).

```yaml
paths:
Expand Down
4 changes: 2 additions & 2 deletions specification-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ To be entirely precise, an OpenAPI document is a single JSON object containing f

The OAS structure is long and complex so this section just describes the minimal set of fields it must contain, while following pages give more details about specific objects. The [OpenAPI Map](https://openapi-map.apihandyman.io/) is a nice visual tool that can help familiarize the reader with this long specification.

The root object in any OpenAPI document is the [OpenAPI Object](https://spec.openapis.org/oas/v3.1.0#oasObject) and only three of its fields are mandatory: `openapi`, `info` and `paths`.
The root object in any OpenAPI document is the [OpenAPI Object](https://spec.openapis.org/oas/v3.1.0#oasObject) and only two of its fields are mandatory: `openapi`, and `info`. Additionally, at least one of `paths`, `components` and `webhooks` is required.

* `openapi` (**string**): This indicates the version of the OAS this document is using, e.g. "3.1.0". Using this field tools can check that the document correctly adheres to the spec.
* `info` ([Info Object](https://spec.openapis.org/oas/v3.1.0#infoObject)): This provides general information about the API (like its description, author and contact information) but the only mandatory fields are `title` and `version`.
Expand Down Expand Up @@ -108,6 +108,6 @@ This page has shown that:

* The syntax (language) used to write OpenAPI documents can be **JSON**, **YAML** or **both**.
* An OpenAPI document is a JSON object including the fields described in the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0).
* Every OpenAPI document must contain a root object with at least the fields `openapi`, `info` and `paths`.
* Every OpenAPI document must contain a root object with at least the fields `openapi`, and `info`, and either `paths`, `components` or `webhooks`.

[The following page](specification-paths.md) describes the contents of the `paths` field so endpoints can be added to the above minimal snippet.