Meaning of the string keys in maps inside the Components object

[arielmirra]

Hi! I noticed that in the componentsObject section of the spec each field is a Map[string, Object]. While debugging some code I realized that this key was used as the name of each parameter declared in parameters. The spec does not make clear what this string means.

Its an identifier? how should be used? What takes precedence in naming a parameter, this string, or the field name inside the parameter object? what happens if both are present?

A little explanation should be added to avoid confusion with key names and actual object names.

Thanks!

[hkosova]

In case of parameters, the actual parameter name is specified by the name field in the parameter definition, and this name is required. The key in the components/parameters map is only used in the $ref path when referencing this parameter. They map key does not have to be the same as the parameter name, it's up to the author of an OpenAPI document.

For example:

components:
  parameters:
    limitParam:     # <----- last part of the $ref path
      in: query
      name: limit   # <----- actual parameter name
      schema:
        type: integer
        minimum: 1
        maximum: 100

This parameter is named limit, but the $ref path would use limitParam:

parameters:
  - $ref: '#/components/parameters/limitParam'

[arielmirra]

Thank you for your clarification!

[handrews]

Answered, closing.