-
-
Save MikeRalphson/7ee0624fc1df70c0475717d89a5b6e4b to your computer and use it in GitHub Desktop.
openapi: 3.1.0-pre1 | |
info: | |
title: API | |
version: 1.0.0 | |
components: | |
parameters: | |
... | |
headers: | |
... | |
traits: | |
# each traitObject MUST have a parameters array XOR a response headers map | |
# + optionally, a summary, description and externalDocs object | |
# and a property: global (boolean, default false) to indicate it applies without exception to all operations/responses | |
# possibly could be expanded with requestBody, responses and links properties | |
# traits are layered in the order they are applied, and local conflicting definitions override those from traits | |
version: | |
global: true # applies to all pathItems | |
parameters: | |
- name: version | |
in: query | |
required: true | |
schema: | |
type: string | |
pagination: | |
parameters: | |
- $ref: '#/components/parameters/pageNo' | |
- $ref: '#/components/parameters/perPage' | |
externalDocs: | |
url: 'https://megadodopublications.com/api/pagination' | |
rateLimiting: | |
headers: | |
'X-Rate-Limited': | |
$ref: '#/components/headers/xRateLimited' | |
'X-Requests-Left': | |
$ref: '#/components/headers/xRequestsLeft' | |
externalDocs: | |
description: 'Find out more about rate limiting' | |
url: 'https://megadodopublications.com/api/rate-limiting' | |
paths: | |
/: | |
get: | |
traits: | |
- $ref: '#/components/traits/pagination' | |
responses: | |
'200': | |
description: OK | |
traits: | |
- $ref: '#/components/traits/rateLimiting' |
Updated to move traits
under components
and use $ref
s as suggested above by @ioggstream, in order to allow inline, referenced or external traits
.
Updated to clarify trait
object must have parameters
XOR a responses headers
map
The idea of using components/overlays
or components/updates
may be a worthwhile alternative to explore.
IMHO the global
flag may be problematic because it modifies a component outside its scope.
https://gist.github.com/MikeRalphson/7ee0624fc1df70c0475717d89a5b6e4b#file-traits-yaml-L17
@ioggstream I can see the potential downside of that approach, but without some way to invoke traits globally, we're not necessarily answering the original requests for this feature.
What about a top-level traits
or globalTraits
array (containing trait objects or $refs)?
If you mean a globalTraits at the same level of "paths" it seems reasonable.
Interesting, but I don't believe YAML anchors are technically allowed by the spec, as they have no equivalent JSON representation (apart from duplication, and that only in non-circular cases).