(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.

additional parameter

It is possible to add additional parameters that is not described in the OpenAPI. For example HttpServletRequest which may be needed to get something from the request that is not described in the api.

While it is possible to add it at the global level, it is best used at the endpoint level.

openapi-processor-mapping: v12

options:
  package-name: generated

map:
  paths:
    /foo:
      parameters:
        - add: request => javax.servlet.http.HttpServletRequest

Given the mapping configuration above and the following endpoint description:

openapi: 3.1.0
info:
  title: test additional endpoint parameter
  version: 1.0.0

paths:
  /foo:
    get:
      parameters:
        - name: foo
          description: query, required
          in: query
          required: true
          schema:
            type: string
      responses:
        '204':
          description: empty

the processor will generate the endpoint method with an additional parameter request:

package generated.api;

import annotation.Mapping;
import annotation.Parameter;
import generated.support.Generated;
import javax.servlet.http.HttpServletRequest;

@Generated(value = "openapi-processor-core", version = "test")
public interface Api {

    @Mapping("/foo")
    void getFoo(
            @Parameter String foo,
            @Parameter HttpServletRequest request);

}

^[1]

unnecessary parameter

It may also be useful to remove a parameter, maybe it is handled by a request filter and is not needed by the endpoint method.

Again, even if it is possible to add it at the global level, it is best used at the endpoint level.

openapi-processor-mapping: v12

options:
  package-name: generated

map:
  paths:
    /foo:
      parameters:
        - drop: foo

Given the configuration above and the following endpoint description:

openapi: 3.1.0
info:
  title: test unnecessary endpoint parameter
  version: 1.0.0

paths:
  /foo:
    get:
      parameters:
        - name: foo
          description: query, required
          in: query
          required: true
          schema:
            type: string
      responses:
        '204':
          description: empty

the processor will generate the endpoint method without the foo parameter.

package generated.api;

import annotation.Mapping;
import generated.support.Generated;

@Generated(value = "openapi-processor-core", version = "test")
public interface Api {

    @Mapping("/foo")
    void getFoo();

}

^[1]

1. note that the annotation used here are just simplified test annotations, the real code will have the proper framework annotations