Structural improvements: Enable the use of (atomic) definition for query, path and header parameters

[arno-di-loreto]

When we define a query, path or header parameter we cannot use a reference to an existing definition.

If I create a Username definition to describe a string which is a username with a certain length and a regex pattern, I can use it in any definition I want.

But if I want to describe a Username path parameter with the same characteristics, I cannot use a schema (only availble if in value is body). So I'll have to define again the characteristics of this Username atomic definition in the UsernameParameter.

Before: Username is described twice

paths:
  /persons/{username}:
    get:
      parameters:
        - $ref: '#/parameters/UsernameParameter'
      responses:
        '200':
          description: A person
          schema:
            $ref: '#/definitions/Person'
definitions:
  Username:
    description: A person's username
    type: string
    pattern: '[a-z0-9]{8,64}'
    minLength: 8
    maxLength: 64
  Person:
    properties:
      username:
        # we can reference the atomic definition Username in any definition
        $ref: '#/definitions/Username'
      firstname:
        type: string
      lastname:
        type: string
      friends:
        type: array
        items:
          # we can reference the atomic definition Username in any definition
          $ref: '#/definitions/Friend'
  Friend:
    properties:
      username:
        $ref: '#/definitions/Username'
parameters:
  UsernameParameter:
    name: username
    in: path
    required: true
    # but we cannot reference the atomic definition Username in atomic parameters
    # username is described twice
    description: A person's username
    type: string
    pattern: '[a-z0-9]{8,64}'
    minLength: 8
    maxLength: 64

If we could use schema: Username is described only once

paths:
  /persons/{username}:
    get:
      parameters:
        - $ref: '#/parameters/UsernameParameter'
      responses:
        '200':
          description: A person
          schema:
            $ref: '#/definitions/Person'
definitions:
  Username:
    description: A person's username
    type: string
    pattern: '[a-z0-9]{8,64}'
    minLength: 8
    maxLength: 64
  Person:
    properties:
      username:
        $ref: '#/definitions/Username'
      firstname:
        type: string
      lastname:
        type: string
      friends:
        type: array
        items:
          $ref: '#/definitions/Friend'
  Friend:
    properties:
      username:
        $ref: '#/definitions/Username'
parameters:
  UsernameParameter:
    name: username
    in: path
    required: true
    # username can be used in an atomic parameted and is described once
    schema:
      $ref: '#/definitions/Username'

[arno-di-loreto]

parent #565

[ePaul]

For the next version, all parameters now have a schema property (added in #654). I guess this solves your problem?

[arno-di-loreto]

Definitely!