2022.6

annotation mapping

annotation mappings allows to add additional annotations to an OpenAPI source type.

(this originates from openapi-processor/openapi-processor-spring#143 advanced validation support, but has changed into a more general solution)

Currently, this is available as

• global annotation type mapping:

  it adds an annotation to the model class generated for the source type.

• global & endpoint parameter annotation type mapping:

  it adds an annotation to a parameter of the source type. Since a request body is passed as parameter the mapping will work for it too.

The global annotation mapping should be added to the map/types or map/parameters section in the mapping.yaml.

The endpoint (http method) mapping restricts the mapping to a specific endpoint. This will go to the map/paths/<endpoint-path>/parameters section in the mapping.yaml.

The annotation type mapping is similar to other mappings and is defined like this:

- type: {source type} @ {annotation type}

Here is an examples mapping.yaml that defines additional annotations for two schemas (model classes) Foo & Bar:

openapi-processor-mapping: v2.1 # <1>

options:
  package-name: io.openapiprocessor.openapi
  bean-validation: true

map:
  types:
    - type: Bar @ io.openapiprocessor.samples.validations.Sum(24) # <2>

  parameters:
    - type: Foo @ io.openapiprocessor.samples.validations.Sum(value = 42) # <3>

      # this formats do work too <4>
      # - type: Foo @ annotation.Bar
      # - type: Foo @ annotation.Bar()
      # - type: Foo @ annotation.Bar("bar")
      # - type: Foo @ annotation.Bar(value = "bar", foo = 2)

The Sum annotation in the example is a custom bean validation but the feature itself is not limited to bean validation.

<1> use v2.1 as the mapping version to avoid validation warnings in the mapping file.
<2> the Bar mapping is using a global type annotation mapping, so the annotation is added to the generated Bar class.
<3> the Foo mapping adds the annotation to the parameter of the endpoint methods that use Foo.
<4> this is a list of examples that shows annotation parameters.

The Bar annotation mapping will produce the Bar model class with the additional annotation on the class:

@Sum(24) // <1>
public class Bar { /* ... */ }

The Foo annotation parameter mapping will produce the endpoint with the additional annotation on the Foo parameter:

    @PostMapping(/*...*/)
    Foo postFoo(@RequestBody @Sum(value = 42) @Valid @NotNull Foo body);

The full example is available in the spring validation sample.

openapi-processor/openapi-processor-spring#144, use annotation for generated code instead of comment

the processor now generates a @Generated annotation and adds it to all generated interfaces and classes instead of the text header.

Some tools recognize the @Generated annotation and exclude them from processing. For example, jacoco will automatically exclude the @Generated files from the code coverage.

this will look like this:

package io.openapiprocessor.release;

import io.openapiprocessor.release.support.Generated;
import org.springframework.web.bind.annotation.GetMapping;

@Generated(value = "openapi-processor-spring", version = "2022.6", date = "2022-09-28T18:37:33.250622+02:00")
public interface ReleaseApi {
// ...
}

Because of the longish date the code formatter will probably add a few line breaks.

Generation of the data parameter can be disabled by setting the generated-date option to false:

openapi-processor-mapping: v2.1 # <1>

options:
  package-name: io.openapiprocessor.openapi
  generated-date: false

<1> use v2.1 as the mapping version to avoid validation warnings in the mapping file.

openapi-processor/openapi-processor-spring#140 additional parameter configuration did not working in global context

using an additional parameter in the global context was not implemented.

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

#99 windows path handling

was broken since 2022.5