From 4add431e6585490d150a0c5221116955d8fffb1c Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 18 Nov 2024 18:10:40 +0000 Subject: [PATCH 1/4] Add an intro to Overlays and one example. Update glossary --- glossary.md | 2 +- overlay/example-add-license.md | 30 ++++++++++++++++++++++++++++++ overlay/index.md | 28 ++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+), 1 deletion(-) create mode 100644 overlay/example-add-license.md create mode 100644 overlay/index.md diff --git a/glossary.md b/glossary.md index bbc10d7..6479064 100644 --- a/glossary.md +++ b/glossary.md @@ -31,7 +31,7 @@ These acronyms are commonly used in OpenAPI discussions, and are defined in the - **OpenAPI Initiative** (OAI): The organization responsible for the development of the OpenAPI Specification _(not to be confused with the unrelated and more recent "OpenAI")_, [website](https://openapis.org/) - **OpenAPI Specification** (OAS): The formal requirements for the OpenAPI format, which exists in several versions (e.g., 3.0.3, 3.1.0) ([repository](https://github.com/OAI/OpenAPI-Specification)) - **Outreach Committee**: The group of volunteers dedicated to furthering the reach and impact of the OAS ([repository](https://github.com/OAI/Outreach)) -- **Overlay Specification**: A proposed specification from the overlays SIG ([repository](https://github.com/OAI/Overlay-Specification)) +- **Overlay Specification**: A specification to describe repeatable edits to apply to an OpenAPI description ([repository](https://github.com/OAI/Overlay-Specification)) - **Special Interest Group** (SIG): OpenAPI working groups focused on [specific topics](https://github.com/OAI/OpenAPI-Specification/blob/main/SPECIAL_INTEREST_GROUPS.md) related to the OAS or possible additional companion specifications - **Technical Developer Community** (TDC): The community of developers and specification-writers who work on and provide feedback to OpenAPI projects ([weekly Zoom calls](https://github.com/OAI/OpenAPI-Specification/issues?q=is%3Aissue+is%3Aopen+%22Open+Community+%28TDC%29+Meeting%22) are on Thursdays from 9-10 AM US-Pacific) - **Technical Steering Committee** (TSC): The [group of people](https://github.com/OAI/OpenAPI-Specification/blob/main/MAINTAINERS.md) charged with stewarding the OAI's specification work, as described in the [OAI Charter](https://www.openapis.org/participate/how-to-contribute/governance) diff --git a/overlay/example-add-license.md b/overlay/example-add-license.md new file mode 100644 index 0000000..b3c64b6 --- /dev/null +++ b/overlay/example-add-license.md @@ -0,0 +1,30 @@ +--- +layout: default +parent: Overlays +nav_order: 2 +title: 'Example: add a license' +has_toc: false +--- + +# Example: add a license + +Every API needs a license so people know they can use it, but what if your OpenAPI descriptions don't have a license? +This example shows an Overlay that adds a license to an OpenAPI description. + +Here's here's the overlay file, with just one action to add or change the `info.license` fields: + +```yaml +overlay: 1.0.0 +info: + title: Add MIT license + version: 1.0.0 +actions: + - target: '$.info' + update: + license: + name: MIT + url: https://opensource.org/licenses/MIT +``` + +You can use this Overlay with different OpenAPI files to make the same change to a batch of files. + diff --git a/overlay/index.md b/overlay/index.md new file mode 100644 index 0000000..11c1799 --- /dev/null +++ b/overlay/index.md @@ -0,0 +1,28 @@ +--- +layout: default +nav_order: 8 +title: Overlays +has_children: true +has_toc: false +--- + +# Introduction to OpenAPI Overlay Specification + +The [Overlay Specification](https://spec.openapis.org/overlay/latest.html) defines a document format for information that augments an existing OpenAPI description yet remains separate from the OpenAPI description's source document(s). + +Overlays support a range of scenarios, including: + +- Translating documentation into another language +- Providing configuration information for different deployment environments +- Allowing separation of concerns for metadata such as gateway configuration or SLA information +- Supporting a traits-like capability for applying a set of configuration data, such as multiple parameters or multiple headers, for targeted objects +- Providing default responses or parameters where they were not explicitly provided +- Applying configuration data globally or based on filter conditions + +## Resources for working with Overlays + +The [GitHub repository for Overlays](https://github.com/oai/Overlay-Specification) is the main hub of activity on the Overlays project. +Check the issues and pull requests for what is currently in progress, and the discussions for details of future ideas and our regular meetings. + +The project maintains a [list of tools for working with Overlays](https://github.com/OAI/Overlay-Specification/?tab=readme-ov-file#tools-that-support-overlays). + From f94d0de7865d3cc3570187f6cc800a493b30f48d Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 26 Nov 2024 21:32:20 +0000 Subject: [PATCH 2/4] Add more examples and some wording updates --- overlay/example-add-filter-parameters.md | 46 ++++++++++++++++++++++++ overlay/example-tag-delete-endpoints.md | 29 +++++++++++++++ overlay/index.md | 3 ++ 3 files changed, 78 insertions(+) create mode 100644 overlay/example-add-filter-parameters.md create mode 100644 overlay/example-tag-delete-endpoints.md diff --git a/overlay/example-add-filter-parameters.md b/overlay/example-add-filter-parameters.md new file mode 100644 index 0000000..47f0618 --- /dev/null +++ b/overlay/example-add-filter-parameters.md @@ -0,0 +1,46 @@ +--- +layout: default +parent: Overlays +nav_order: 5 +title: 'Example: add params selectively' +has_toc: false +--- + +# Example: Add multiple parameters to selected operations + +One of the most requested features for OpenAPI is the ability to group parameters and easily apply all of them together, to either some or all operations in an OpenAPI description. +Especially for common parameters that always come as a set (pagination or filter parameters are a great example), it can be more maintainable to use them as a "trait" and apply the set as part of the API lifecycle rather than trying to maintain a source of truth that has all the correct fields everywhere. + +In the following example, any operations with the extension `x-supports-filters` set to `true` will have two inline parameters added to their parameter collection, and an `x-filters-added` tag for decoration/debugging. + +```yaml +overlay: 1.0.0 +info: + title: Add filter parameters everywhere + version: 1.0.0 +actions: +- target: $.paths.*.*[?(@.x-supports-filters == true)] + update: + parameters: + - name: month + in: query + description: Month number of event (1-12) + required: false + type: integer + + - name: time_start + in: query + description: Start time of event + required: false + type: string + tags: + - x-filters-added +``` + +You can adjust the target expression to apply only to certain paths or methods, or use another approach to identify which operations should be used. + +It might be more elegant to first update the `components.parameters` section of an OpenAPI description to add the parameters there, and then refer to those new entries when updating the existing operations. +The Overlay Specification requires that each action is processed in the order it is seen in the Overlay document. + +The 1.0 specification has a [traits example](https://spec.openapis.org/overlay/v1.0.0.html#traits-example) that uses the `x-oas-traits` extension. +This extension is a useful convention to consider when you use a pattern like the one described here. diff --git a/overlay/example-tag-delete-endpoints.md b/overlay/example-tag-delete-endpoints.md new file mode 100644 index 0000000..3ac4ef8 --- /dev/null +++ b/overlay/example-tag-delete-endpoints.md @@ -0,0 +1,29 @@ +--- +layout: default +parent: Overlays +nav_order: 3 +title: 'Example: tag DELETE operations' +has_toc: false +--- + +# Example: tag DELETE operations + +To add the same tag to all operations in an OpenAPI description that use `DELETE` methods, use an Overlay like the example below. +This example adds an `x-restricted` tag to all delete operations: + +```yaml +overlay: 1.0.0 +info: + title: Tag delete operations as restricted + version: 1.0.0 +actions: +- target: $.paths.*.delete + update: + tags: + - x-restricted +``` + +This overlay adds `x-restricted` to the tags array for each delete operation. +If the tags array doesn't exist, it'll be created; if it does, the new tag is added to the existing array. + +You can use an approach like this to make other changes to all matching operations. diff --git a/overlay/index.md b/overlay/index.md index 11c1799..95eb99e 100644 --- a/overlay/index.md +++ b/overlay/index.md @@ -9,6 +9,9 @@ has_toc: false # Introduction to OpenAPI Overlay Specification The [Overlay Specification](https://spec.openapis.org/overlay/latest.html) defines a document format for information that augments an existing OpenAPI description yet remains separate from the OpenAPI description's source document(s). +An Overlay can be applied to an OpenAPI description, resulting in an updated OpenAPI description. + +> **OpenAPI + Overlays = (better) OpenAPI** Overlays support a range of scenarios, including: From bcc188fc69959dc9623b1839a43e4dc5b80b09b9 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 27 Nov 2024 14:37:42 +0000 Subject: [PATCH 3/4] Updates from pull request reviews --- overlay/example-add-filter-parameters.md | 5 +++-- overlay/index.md | 9 ++++++++- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/overlay/example-add-filter-parameters.md b/overlay/example-add-filter-parameters.md index 47f0618..f4de5fe 100644 --- a/overlay/example-add-filter-parameters.md +++ b/overlay/example-add-filter-parameters.md @@ -9,7 +9,8 @@ has_toc: false # Example: Add multiple parameters to selected operations One of the most requested features for OpenAPI is the ability to group parameters and easily apply all of them together, to either some or all operations in an OpenAPI description. -Especially for common parameters that always come as a set (pagination or filter parameters are a great example), it can be more maintainable to use them as a "trait" and apply the set as part of the API lifecycle rather than trying to maintain a source of truth that has all the correct fields everywhere. +Especially for common parameters that always come as a set (pagination or filter parameters are a great example), it can be more maintainable to use them as a "trait" and apply the set as part of the API lifecycle rather than trying to maintain a source of truth with a lot of repetition. +This approach leads to good API governance, since if the collection of fields changes then the update is consistently applied through automation. In the following example, any operations with the extension `x-supports-filters` set to `true` will have two inline parameters added to their parameter collection, and an `x-filters-added` tag for decoration/debugging. @@ -42,5 +43,5 @@ You can adjust the target expression to apply only to certain paths or methods, It might be more elegant to first update the `components.parameters` section of an OpenAPI description to add the parameters there, and then refer to those new entries when updating the existing operations. The Overlay Specification requires that each action is processed in the order it is seen in the Overlay document. -The 1.0 specification has a [traits example](https://spec.openapis.org/overlay/v1.0.0.html#traits-example) that uses the `x-oas-traits` extension. +The 1.0 specification has a [traits example](https://spec.openapis.org/overlay/v1.0.0.html#traits-example) that uses the `x-oas-traits` [Specification Extension](https://spec.openapis.org/oas/v3.1.1.html#specification-extensions). This extension is a useful convention to consider when you use a pattern like the one described here. diff --git a/overlay/index.md b/overlay/index.md index 95eb99e..ca3cb12 100644 --- a/overlay/index.md +++ b/overlay/index.md @@ -8,11 +8,18 @@ has_toc: false # Introduction to OpenAPI Overlay Specification -The [Overlay Specification](https://spec.openapis.org/overlay/latest.html) defines a document format for information that augments an existing OpenAPI description yet remains separate from the OpenAPI description's source document(s). +The [Overlay Specification](https://spec.openapis.org/overlay/latest.html) defines a document format for information that transforms an existing OpenAPI description yet remains separate from the OpenAPI description's source document(s). +The goal of the Overlay Specification is to provide a mechanism for providing consistent, deterministic updates to a given OpenAPI description, as an aid to automation throughout the API lifecycle. + An Overlay can be applied to an OpenAPI description, resulting in an updated OpenAPI description. > **OpenAPI + Overlays = (better) OpenAPI** +One Overlay might be specific to one OpenAPI description, or general enough to be used with multiple OpenAPI descriptions. +Equally, one OpenAPI description pipeline might apply different Overlays during the workflow. + +## Use cases for Overlays + Overlays support a range of scenarios, including: - Translating documentation into another language From ccfd62ebd2a56771ed55e05c738551d1b9ae49c9 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 27 Nov 2024 16:35:30 +0000 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Ralf Handl --- overlay/example-add-filter-parameters.md | 2 +- overlay/example-add-license.md | 2 +- overlay/index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/overlay/example-add-filter-parameters.md b/overlay/example-add-filter-parameters.md index f4de5fe..aa2bf19 100644 --- a/overlay/example-add-filter-parameters.md +++ b/overlay/example-add-filter-parameters.md @@ -38,7 +38,7 @@ actions: - x-filters-added ``` -You can adjust the target expression to apply only to certain paths or methods, or use another approach to identify which operations should be used. +You can adjust the target expression to apply only to certain paths or methods, or use another approach to identify which operations should be updated. It might be more elegant to first update the `components.parameters` section of an OpenAPI description to add the parameters there, and then refer to those new entries when updating the existing operations. The Overlay Specification requires that each action is processed in the order it is seen in the Overlay document. diff --git a/overlay/example-add-license.md b/overlay/example-add-license.md index b3c64b6..9bdd660 100644 --- a/overlay/example-add-license.md +++ b/overlay/example-add-license.md @@ -11,7 +11,7 @@ has_toc: false Every API needs a license so people know they can use it, but what if your OpenAPI descriptions don't have a license? This example shows an Overlay that adds a license to an OpenAPI description. -Here's here's the overlay file, with just one action to add or change the `info.license` fields: +Here's the Overlay file, with just one action to add or change the `info.license` fields: ```yaml overlay: 1.0.0 diff --git a/overlay/index.md b/overlay/index.md index ca3cb12..d437d80 100644 --- a/overlay/index.md +++ b/overlay/index.md @@ -9,7 +9,7 @@ has_toc: false # Introduction to OpenAPI Overlay Specification The [Overlay Specification](https://spec.openapis.org/overlay/latest.html) defines a document format for information that transforms an existing OpenAPI description yet remains separate from the OpenAPI description's source document(s). -The goal of the Overlay Specification is to provide a mechanism for providing consistent, deterministic updates to a given OpenAPI description, as an aid to automation throughout the API lifecycle. +The Overlay Specification defines a mechanism for providing consistent, deterministic updates to a given OpenAPI description, as an aid to automation throughout the API lifecycle. An Overlay can be applied to an OpenAPI description, resulting in an updated OpenAPI description.