Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added example of making overlays work like traits #2534

Merged
merged 1 commit into from
Apr 12, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions proposals/004_Overlays.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,43 @@ updates:
remove: true
```

##### Traits Examples

By annotating an OpenAPI description using extension such as `x-oai-traits` an author of OpenAPI description can identify where overlay updates should be applied.

```yaml
openapi: 3.1.0
info:
title: Api with a paged collection
version: 1.0.0
paths:
/items:
get:
x-oai-traits: ["paged"]
responses:
200:
description: OK
```

With the above OpenAPI description, following Overlay document will apply the necessary updates to describe how paging is implemented, where that trait has been applied.

```yaml
overlay: 1.0.0
info:
title: Apply Traits
version: 1.0.0
updates:
- target: $.paths[*].get[?contains(x-traits,'paged')]
merge:
parameters:
- name: top
in: query
- name: skip
in: query
```

This approach allows flipping control of where Overlays apply updates to the OpenAPI description itself.

## Proposal Summary

### Benefits
Expand Down