Parameters

query parameters

Query parameters get converted to method parameters with a @RequestParam() annotation.

For example the following query parameter description:

paths:
  /endpoint:
    get:
      parameters:
        - name: foo
          description: simple query parameter with default value
          in: query
          required: false
          schema:
            type: string
            default: 'not set'
      responses:
        '204':
          description: empty

will generate the following interface method:

@GetMapping(path = "/endpoint")
ResponseEntity<Void> getEndpoint(@RequestParam(name = "foo", required = false, defaultValue = "not set") String foo);

path parameters

Path parameters get converted to method parameters with a @PathVariable() annotation.

For example the following endpoint description:

paths:
  /endpoint/{foo}:
    get:
      parameters:
        - name: foo
          description: a path parameter
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: plain text response
          content:
            plain/text:
              schema:
                type: string

will generate the following interface method:

@GetMapping(
        path = "/path/{foo}",
        produces = {"plain/text"})
String getEndpointFoo(@PathVariable(name = "foo") String foo);

header parameters

Header parameters use the @RequestHeader annotation.

Given the following endpoint description:

paths:
  /endpoint:
    get:
      tags:
        - endpoint
      parameters:
        - name: x-foo
          description: a header parameter
          in: header
          required: true
          schema:
            type: string
      responses:
        '204':
          description: empty

the processor generates the following interface method:

@GetMapping(path = "/endpoint")
void getEndpoint(@RequestHeader(name = "x-foo") String xFoo);

Cookie parameters use the @CookieValue annotation.

Given the following endpoint description:

paths:
  /endpoint:

    get:
      parameters:
        - name: foo
          description: a cookie
          in: cookie
          required: true
          schema:
            type: string
      responses:
        '204':
          description: empty

the processor generates the following interface method:

@GetMapping(path = "/endpoint")
void getEndpoint(@CookieValue(name = "foo") String foo);

additional parameters

Sometimes it may be useful to have an additional endpoint parameter that is required for the implementation, but it should not be part of the OpenAPI description. Think of an HttpServletRequest or a custom Spring HandlerMethodArgumentResolver.

Such an additional parameter can be described in the mappings as an endpoint parameter. Assuming there is an endpoint /foo defined in the OpenAPI interfaces it is possible to add extra parameters by using an add <parameter name> as <java type> entry.

map:
  paths:
    /foo:

      parameters:
        - add: request => javax.servlet.http.HttpServletRequest

will add the additional parameter to the generated interface method.

@GetMapping(path = "/foo")
ResponseEntity<?> getFoo(@RequestParam(name = "bar") String bar, HttpServletRequest request);