2

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.

Xedni
  • 3,662
  • 2
  • 16
  • 27

0 Answers0