https://github.com/oai/overlay-specification

The OAI Overlay Specification
https://github.com/oai/overlay-specification

Last synced: about 1 month ago
JSON representation

The OAI Overlay Specification

• Host: GitHub
• URL: https://github.com/oai/overlay-specification
• Owner: OAI
• License: apache-2.0
• Created: 2021-04-20T15:32:43.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2024-09-26T07:35:15.000Z (about 2 months ago)
• Last Synced: 2024-10-07T10:21:56.748Z (about 1 month ago)
• Language: JavaScript
• Homepage:
• Size: 85 KB
• Stars: 49
• Watchers: 21
• Forks: 13
• Open Issues: 18
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Overlay-Specification

The Overlay Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.

The Overlay specification defines a way of creating documents that contain information to be merged with an OpenAPI description at some later point in time, for the purpose of updating the OpenAPI description with additional information.

Overlays can address a wide range of scenarios that have been frequently requested by OpenAPI users:

- Support multi-language API descriptions by using Overlays to contain language translations.

- Provide configuration information for different deployment environments.

- Allow separation of concerns for metadata such as gateway configuration or SLA information.

- Support a traits like capability for applying a set of configuration data, such as multiple parameters, or multiple headers to a targeted object.

- Provide default responses, or parameters where they are not explicitly provided.

- Apply configuration data globally or based on filter conditions.

## Current Status

The current specification is sufficiently stable for implementers to start experimenting.  We are looking for implementation experience to guide our decisions on the remaining open issues.

## Tools that support Overlays

If you are looking for tools to use with Overlays, try these:

- [Bump.sh CLI](https://github.com/bump-sh/cli)

- [Speakeasy CLI](https://www.speakeasy.com/docs/speakeasy-cli/getting-started)

- [overlays-js](https://github.com/lornajane/openapi-overlays-js)

(Is something missing from the list? Send us a pull request to add it!)

## Licensing

See: [License (Apache-2.0)](./LICENSE)