From 26fe1eba5c23961aca47202b063c8f82e79c7881 Mon Sep 17 00:00:00 2001 From: Duncan Beevers Date: Thu, 28 Sep 2023 16:29:58 -0700 Subject: [PATCH 1/5] Describe OpenAPI entry point in OpenAPI description docs --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index eef80f3388..23d415f724 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -69,7 +69,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp ## Definitions ##### 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. +An OpenAPI description describes an API, and is composed of an [entry document](#documentStructure), and all transitively-referenced documents. 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. ##### 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. From a441078e5bc1c2d6e5472805f010afdd81bb6e55 Mon Sep 17 00:00:00 2001 From: Duncan Beevers Date: Thu, 28 Sep 2023 16:42:42 -0700 Subject: [PATCH 2/5] fixup! Describe OpenAPI entry point in OpenAPI description docs --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 23d415f724..1e9f45b6bf 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -69,7 +69,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp ## Definitions ##### OpenAPI Description -An OpenAPI description describes an API, and is composed of an [entry document](#documentStructure), and all transitively-referenced documents. 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. +An OpenAPI description describes an API, and is composed of an [entry document](#documentStructure), and all its referenced documents. 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. ##### 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. From 529a1977b45902743e00c9a16047639e1091260c Mon Sep 17 00:00:00 2001 From: Darrel Date: Thu, 1 Feb 2024 12:09:24 -0500 Subject: [PATCH 3/5] Update versions/3.1.1.md Co-authored-by: Ralf Handl --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 1e9f45b6bf..0de7853215 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -69,7 +69,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp ## Definitions ##### OpenAPI Description -An OpenAPI description describes an API, and is composed of an [entry document](#documentStructure), and all its referenced documents. 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. +An OpenAPI Description (OAD) describes an API, and is composed of an [entry document](#documentStructure) and all its referenced documents. An OAD uses and conforms to the OpenAPI Specification, and MUST contain at least one [paths](#pathsObject) field, [components](#oasComponents) field, or [webhooks](#oasWebhooks) field. ##### 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. From f407f8c54a915af0961b2f6a10bde89aabd1bdb8 Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Thu, 1 Feb 2024 09:23:38 -0800 Subject: [PATCH 4/5] fence braces with backticks Co-authored-by: Ralf Handl --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 0de7853215..e5c8de8e03 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -72,7 +72,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp An OpenAPI Description (OAD) describes an API, and is composed of an [entry document](#documentStructure) and all its referenced documents. An OAD uses and conforms to the OpenAPI Specification, and MUST contain at least one [paths](#pathsObject) field, [components](#oasComponents) field, or [webhooks](#oasWebhooks) field. ##### 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. +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. Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required. From 491189153c24656e27e9047ffcbdc2ce2958d17c Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Thu, 1 Feb 2024 09:53:04 -0800 Subject: [PATCH 5/5] wordsmithing --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index e5c8de8e03..5d0aed2a37 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -69,7 +69,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp ## Definitions ##### OpenAPI Description -An OpenAPI Description (OAD) describes an API, and is composed of an [entry document](#documentStructure) and all its referenced documents. An OAD uses and conforms to the OpenAPI Specification, and MUST contain at least one [paths](#pathsObject) field, [components](#oasComponents) field, or [webhooks](#oasWebhooks) field. +An OpenAPI Description (OAD) formally describes the surface of an API and its semantics. It is composed of an [entry document](#documentStructure) and any/all of its referenced documents. An OAD uses and conforms to the OpenAPI Specification, and MUST contain at least one [paths](#pathsObject) field, [components](#oasComponents) field, or [webhooks](#oasWebhooks) field. ##### 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.