Hopefully this question holds together.
I am building a swagger spec and I want to be able to not only re-use definitions wholesale (i.e. what $ref
does), but build those definitions out of even simpler references.
For example, say I want to describe the concept of an assetId
as both a parameter and a response. I could do something like this:
parameters:
assetId:
name: assetId
in: path
description: Identifier of the asset
type: integer
responses:
assetId:
description: Identifier of the asset
type: integer
and pull #/parameters/assetId
and #/responses/assetId
in for their respective sections, but I still have a seemingly unavoidable duplication of some of the properties (namely description
and type
)
What I'd like to be able to do is break down each of those into atomic pieces, and then compose the parameter and response definitions primarily from those references, something like:
swagger: "2.0"
descriptions:
assetId:
descriptions: Identifier of the assetId
schemas:
assetId:
type: integer
format: int32
examples:
assetId:
example: 205778
paths:
/assets/{assetId}:
get:
parameters:
- name: assetId
in: path
$ref: '#/schemas/assetId'
$ref: '#/descriptions/assetId'
$ref: '#/examples/assetId'
responses:
'200'
and have that final section essentially evaluate to:
...
parameters:
- name: assetId
in: path
type: integer
description: Identifier of the asset
format: int32
example: 205778
... but it's not working; clearly throwing an error that I have a duplicate key in there with the $refs
, but I don't know how else to approach it. Can anyone show me how to do this sort of atomic composition of swagger definitions?
NOTE: I'm using swagger 2.0 at work so if it can be done there that'd be sweet, but even if it's only possible in 3.0, i'd still like to know.