(global) Parameter mappings

Parameter mappings, as the name suggests, apply to the parameters of an endpoint method.

parameter mapping by name

A global parameter mapping will replace any usage of an OpenAPI type in the api description based on the parameters name to the given java type.

Since the processor will simply match the parameter by its name, take care that all parameters of that name should really use the same type!

It is defined like below, and it should be added to the map/parameters section in the mapping.yaml which is a list of global parameter mappings.

A single global parameter mapping can have the following properties:

 - name: {parameter name}  =>  {target type}
   generics:
     - {a generic type}
     - {another generic type}
  • name is required.

    • {parameter name} is the name of an endpoint parameter used in the OpenAPI description that should be replaced by {target type}.

    • {target type} is the fully qualified class name of the java type that should be used for all endpoint content types {parameter name}.

  • generics defines the list of types that should be used as generic type parameters to the java type given by {target type}.

Example

Given the following (global) parameter mapping

map:

  # list of global parameter mappings, mapped by parameter name
  parameters:
    - name: date => java.time.ZonedDateTime

and an openapi.yaml with multiple endpoints having a parameter named "date"

openapi: 3.0.2
info:
  title: global parameter type mapping example
  version: 1.0.0

paths:
  /do-something:
    get:
      parameters:
        - in: query
          name: date
          schema:
            type: integer
      responses:
        '200':
          description: none
          content:
            application/json:
              schema:
                type: object
                properties:
                  prop:
                    type: string

  /do-something-else:
    get:
      parameters:
        - in: query
          name: date
          schema:
            type: string
      responses:
        '200':
          description: none
          content:
            application/json:
              schema:
                type: object
                properties:
                  prop:
                    type: string

the processor will use java.time.ZonedDateTime as java type for all parameters named "date" in all endpoints that have a "date" parameter.

In the example both endpoints would use java.time.ZonedDateTime as java type for the "date" parameter.