PROPOSAL: Partial Parameters Definition / Override parameters values

[oliverhr]

The PARAMETERS DEFINITIONS OBJECT should accept partial definition for parameters or properties overriding:

Currently supported:

...
  /recipe:
    post:
      operationId: recipe_new

      parameters:
        - name: id
          in: query
          description: Recipe ID
          required: true
          type: string
        - name: ingredients
          in: query
          description: list of ingredients
          type: array
          items:
            type: string
          collectionFormat: csv
        - $ref: "#/parameters/FoodType"

      responses:
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
        200:
          description: Success
          schema:
            $ref: "#/definitions/SuccessResponse"


# ---------------------------------------------------
definitions:

  SuccessResponse:
    properties:
      message:
        type: string

  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string
# ---------------------------------------------------
parameters:

  FoodType:
    name: foodType
    description: Type of food on the recipe
    required: true
    in: formData
    type: string
    default: cake
    enum:
      - cake
      - cookies
      - bread

As you can see on the endpoint definition we add FoodType as reference, but we are forced tu use all the defined properties.

It would be good if we could define a partial definition or override something like this:

...
# ---------------------------------------------------
parameters:

  FoodType:
    name: foodType
    description: Type of food on the recipe
    required: true
    type: string
    default: cake
    enum:
      - cake
      - cookies
      - bread

And use like this:

  /recipe:
    post:
      operationId: recipe_new

      parameters:
        - name: id
          in: query
          description: Recipe ID
          required: true
          type: string
        - name: ingredients
          in: query
          description: list of ingredients
          type: array
          items:
            type: string
          collectionFormat: csv
        - $ref: "#/parameters/FoodType"
          in: query
          required: false
...

I defined required as true but later I override this value to false, and in is defined on the endpoint only.

[ePaul]

Generally $ref doesn't work together with other properties in a JSON object. If this were to be changed, this should be done for all the places where $ref is used.

Some related issues: #926, #648, #674, #556.

[fehguy]

yes, supporting that would break all support for JSON pointers, which we really don't want to do.