Merge pull request #115 from lornajane/overlay-docs

Overlay documentation

Author: lornajane

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)

overlay/example-add-filter-parameters.md

@@ -0,0 +1,47 @@
+---
+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 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.
+
+```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 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.
+
+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.

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 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.
+ 

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.

overlay/index.md

@@ -0,0 +1,38 @@
+---
+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 transforms an existing OpenAPI description yet remains separate from the OpenAPI description's source document(s).
+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.
+
+> **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
+- 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).
+