From cdb66ef1f9fe0e3e22b11da982a0c9b324ed6b01 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sun, 22 Aug 2021 13:50:22 -0700 Subject: [PATCH 1/2] "paths" is no longer mandatory --- specification-structure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification-structure.md b/specification-structure.md index a0353e8..ab530e1 100644 --- a/specification-structure.md +++ b/specification-structure.md @@ -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`. @@ -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. From 3a7776a4b163cfd424db07594c1fa1bd90dbd580 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sun, 22 Aug 2021 13:51:32 -0700 Subject: [PATCH 2/2] /paths/responses is no longer mandatory --- specification-paths.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification-paths.md b/specification-paths.md index ee4a36d..f7a606f 100644 --- a/specification-paths.md +++ b/specification-paths.md @@ -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: