Add parameter and response body mapping

[andriy-dmytruk]

These changes are to allow the use of custom types for parameters and response bodies to utilize all Micronaut capabilities for code simplification.

Parameters mapping

As an example, if we add the following parameter mappings:

[
  {name: "page", location: "QUERY", mappedType: "io.micronaut.data.model.Pageable"},
  {name: "size", location: "QUERY", mappedType: "io.micronaut.data.model.Pageable"},
  {name: "sortOrder", location: "QUERY", mappedType: "io.micronaut.data.model.Pageable"},
]

micronaut Pageable will be used for page, size or sortOrder headers:

    @Get("/sendPageQuery")
    @Produces({"application/json"})
    Mono<String> sendPageQuery(
        @NotNull
        Pageable pageable
    );

instead of each header being a separate parameter:

    @Get("/sendPageQuery")
    @Produces({"application/json"})
    Mono<String> sendPageQuery(
        @HeaderParam
        Integer page,
        @HeaderParam
        Integer size,
        @Headerparam
        String sortOrder
    );

The spec in this case is :

operations:
  /sendPageQuery:
    get:
      operationId: sendPageQuery
      tags: [ parameters ]
      description: A method that takes page query as its argument
      parameters:
        - $ref: '#/parameters/PageQueryParam'
        - $ref: '#/parameters/PageSizeQueryParam'
        - $ref: '#/parameters/PageSortQueryParam'
      responses:
        200:
          description: Success
          schema:
            type: string
parameters:
  PageQueryParam:
    name: page
    in: query
    type: integer
    minimum: 0
    default: 0
    description: The page number to retrieve starting from 0.
  PageSizeQueryParam:
    name: size
    in: query
    type: integer
    minimum: 1
    default: 10
    description: The number of items per page.
  PageSortQueryParam:
    name: sortOrder
    in: query
    type: string
    description: |
      Parameter describing the sort. Allows specifying the sorting direction using the keywords {@code asc} and
      {@code desc} after each property. For example, {@code "sort=name,desc,&sort=age"} will sort by name in descending
      order and age in ascending.

Similarly to the example above, custom types can be created with TypedRequestArgumentBinder implementations. Parameters can be ignored by setting the mappedType to null, as some parameters may be consumed inside interceptors or filters.

Response body mapping

The body mapping works in a similar way, but changes the return type of operation. Since server can only return header parameters, the mapping is done based on them.

For example, if we add the following body mapping:

{headerName: "Last-Modified", mappedBodyType: "io.micronaut.openapi.test.dated.DatedResponse"}

the operation would be created as (if a Last-Modified header is specified):

    @Get("/getDatedSimpleModel")
    @Produces({"application/json"})
    Mono<DatedResponse<SimpleModel>> getDatedSimpleModel();

The custom DatedResponse object then would need a MessageBodyWriter implementation and include the required header.

The specification in the case above:

operations:
  /getDatedSimpleModel:
    get:
      operationId: getDatedSimpleModel
      tags: [ responseBody ]
      description: A method to get a simple model with last-modified header
      responses:
        200:
          description: Success
          headers:
            Last-Modified: *Last-Modified-header
          schema:
            $ref: '#/definitions/SimpleModel'
x-headers:
  LastModifiedHeader: &Last-Modified-header
    name: Last-Modified
    type: string
    format: date-time
    description: The last time an entity returned with the response was modified.

Note

We can make this interface available in gradle/maven plugins or keep available for extension generators only.

[yawkat]

Suggested change

System.out.println("json: " + string);

[sonarcloud]

SonarCloud Quality Gate failed.   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
8 Code Smells

0.0% Coverage
0.0% Duplication

Catch issues before they fail your Quality Gate with our IDE extension SonarLint