Support passing arguments to referenced objects

[tenodi]

I want my API documentation to be concise. Therefor, I want to define anything repeating in the top level members in Swagger object. Since I'm using JSON API , I have some boilerplate, as data followed by the actual representation in the resource. Usual definition of 201 response, looks like:

 responses:
   Created:
     description: new resource
     headers:
       Location:
         type: string
         format: uri
     schema:
       type: object
       required:
       - data
       properties:
       - data:
           $ref: '#/definitions/resourceDefinition'

I will use that Created definition in my Operations object as:

 responses:
   '201':
     $ref: '#/definitions/Created'

And that's great. But, how can I pass an argument in the form of resourceDefinition and any other parts that I will need? Every API endpoint has its own resource definitions (and other specifics) and my API documentation (in comments in above the code) would be too large to write it constantly. I failed to find a way to pass argument to referenced object.

Is there anything I could do?

This is what I would like to be able to do:

Docs above my API endpoint:

 responses:
   '201':
     $ref: '#/definitions/Created'
     args:
     - resourceDefinition: '#/definitions/Foo'

Docs in top level responses property:

 responses:
   Created:
     description: new resource
     headers:
       Location:
         type: string
         format: uri
     schema:
       type: object
       required:
       - data
       properties:
       - data:
           $ref: '#args/resourceDefinition'

[ePaul]

So basically you want parameterized data types?

I don't think this is something which the OpenAPI spec wants to do, though maybe some kind of tooling can pre-process your input into the official form.

Though maybe this can be incorporated in some way in #555 (or meta-issue #586).

[ralfhandl]

This sounds similar to the parameterized templates/patterns for Path Item objects that I proposed in #588.

[webron]

Closing this as it is indeed duplicated over tickets mentioned in #555 and should be covered there (best to keep discussions in one place). Personally, I see the value in parameterized data types, which is a solution to the problem.

@tenodi - keep in mind that your proposal will not work unless we decide to go with a 'fix' for #556.