What’s New

January 2023

  • openapi-processor-spring/micronaut 2023.1

support requestBody $ref

the processor is now able to resolve $ref s of requestBody (This works with all 3 OpenAPI parsers).

openapi: 3.1.0
info:
  title: components requestBodies
  version: '1.0'

paths:
  /foo:
    post:
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: string
      requestBody:
        $ref: '#/components/requestBodies/Foo'  (1)

components:
  requestBodies:
    Foo:
      content:
        application/json:
          schema:
            type: object
            properties:
              foo:
                type: string
1 $ref is direct child of requestBody.

annotation mapping support for simple data types

it is now possible to add an annotation mapping for simple data types (format works too):

openapi-processor-mapping: v3

map:
  types:
    - type: string:uuid => java.util.UUID
    - type: string:uuid @ annotation.Bar

openapi-processor will add it on any string:uuid property used in the generated model classes:

@Generated
public class Foo {

    @Bar
    @JsonProperty("foo")
    private UUID foo;

     // ....
}

annotation mapping support for mapped types

in the previous version an annotation mapping was lost if the type was mapped at the same time to an existing class. It will now add the annotation to the existing class if possible.

Assume the following mapping:

openapi-processor-mapping: v3

options:

map:
  types:
    - type: Foo => openapiprocessor.MappedFoo
    - type: Foo @ annotation.Bar  (1)

  parameters:
     - type: Foo @ annotation.Bar (2)

MappedFoo is a class that is not generated. Adding an annotation at the parameter level works as expected (mapping <2>). But it is not possible to add the Bar annotation directly at the class (mapping <1>):

@Bar
@Generated
public class Foo {
    // ....
}

instead, openapi-processor will add it on any MappedFoo property used in the generated model classes:

@Generated
public class FooBar {

    @Bar
    @JsonProperty("foo")
    private MappedFoo foo;

     // ....
}

bean validation v3 support

Spring Boot 3 updates bean validations to v3. In v3 the package name changed from javax to jakarta. It is now possible to select between the v2 & v3 version in the mapping.yaml.

the new mapping schema v3 adds javax and jakarta as possible values for the bean-validation option. true/false will still work as before.

# use v3 for proper validation of the mapping file
openapi-processor-mapping: v3

options:
  # no bean validation, as before
  bean-validation: false

  # enable bean validation, as before (will use `javax...`)
  bean-validation: true

  # new: enable bean validation with `javax...`
  bean-validation: javax

  # new: enable bean validation with `jakarta...`
  bean-validation: jakarta

bean validation support on mapped data types

openapi-processor now preserves bean validation annotations when the source data type is mapped to an existing class. This is most interesting for the @Valid annotation.

It adds the annotations it would add on the source data type. In previous versions the annotations got lost when the data type was mapped to an existing class. Without`@Valid` the validation would not be triggered on the mapped object.

having this OpenAPI description

openapi: 3.1.0
info:
  title: mapped bean validation
  version: 1.0.0

paths:
  /foo:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Foo'
      responses:
        204:
          description: none

components:
  schemas:
    Foo:
      type: object
      properties:
        foo:
          type: integer
          minimum: 0

the endpoint looks like this without a mapping that replaces Foo (ignore the @Mapping/@Parameter annotations, this is pseudo code used by the integration tests):

package generated.api;

import annotation.Mapping;
import annotation.Parameter;
import generated.model.Foo;
import javax.validation.Valid;

public interface Api {

    @Mapping("/foo")
    void postFoo(@Parameter @Valid Foo body);   // has @Valid annotation

}

with a mapping that replaces Foo with Bar

openapi-processor-mapping: v3

options:
  package-name: generated
  bean-validation: true

map:
  types:
    - type: Foo => openapiprocessor.Bar

it will now generate the endpoint with a @Valid on the mapped data type.

package generated.api;

import annotation.Mapping;
import annotation.Parameter;
import javax.validation.Valid;
import openapiprocessor.Bar;

public interface Api {

    @Mapping("/foo")
    void postFoo(@Parameter @Valid Bar body);   // new: has @Valid annotation

}

October 2022

  • openapi-processor-spring/micronaut 2022.5

annotation mapping

this is a new feature.

It allows to place additional annotations on generated model classes. It is possible to place the annotation at the class itself or on parameters of that type.

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)

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.

See annotation mapping for the details.

@Generated

This will replace the text header from the generated files with a (generated) @Generated annotation.

Other tools may be able to detect the generated files and ignore them.

For example jacoco automatically ignores @Generated classes. It is no longer necessary to exclude the generated files from code coverage.

A generated interface/class will now 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.

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

@HeadMapping/@TraceMapping/@OptionsMapping do not exist

a few http methods do not have an explicit mapping annotation: @HeadMapping, @TraceMapping, @OptionsMapping.

The processor now generates @RequestMapping(method = RequestMethod. {http method} )) .

windows path handling

was broken since 2022.4

May 2022

  • openapi-processor-spring/micronaut 2022.4

openapi-processor offers a new alternative OpenAPI 3.0 & 3.1 parser and fixes missing bean validation imports

  • OpenAPI 3.0 support includes JSON schema validation with detailed reporting.

  • OpenAPI 3.1 support is experimental and does not yet support schema validation.

OpenAPI 3.0 parser & JSON schema validation

openapi-processor provides an alternative internal OpenAPI 3.0 parser. It includes JSON schema validation with detailed reporting.

To enable it, set the parser configuration to INTERNAL.

// build.gradle processor configuration

openapiProcessor {
    spring {
        processor 'io.openapiprocessor:openapi-processor-spring:2022.4'

        apiPath "${projectDir}/src/api/openapi.yaml"
        targetDir "$projectDir/build/openapi"
        mapping "${projectDir}/src/api/mapping.yaml"

        // use internal OpenAPI parser
        parser 'INTERNAL'
    }
}

OpenAPI 3.1 (experimental)

The internal OpenAPI parser supports OpenAPI 3.1 but does not yet have schema validation.

To enable it, set the parser configuration to INTERNAL. It will automatically detect OpenAPI 3.0 & 3.1.

The processor does handle the renamed/changed OpenAPI 3.1 properties as needed for code generation:

type keyword

The type keyword allows a list of types. Defining a nullable type is done by adding "null" to the list of types.

# OpenAPI v3.0
type: string
nullable: true

# OpenAPI v3.1
type:
- "string"
- "null"

The processor does support the new nullable definition. Apart from that it will use the first non-null type as the type for code generation.

exclusiveMinimum and exclusiveMaximum keywords

# OpenAPI v3.0
maximum: 42
exclusiveMaximum: true

# OpenAPI v3.1
exclusiveMaximum: 42

which is used for adding bean validations.

missing import for javax.validation.constraints.Pattern

the `import`s for bean validation annotations were missing for item constraints of a mapped array. Having an api description like this

paths:
  /test:
    get:
      parameters:
        - in: query
          name: patternParam
          required: false
          description: query parameter with @Pattern annotation
          schema:
            $ref: '#/components/schemas/PatternParam'
      responses:
        '200':
          description: ok
  schemas:
    PatternParam:
      type: array
      items:
        type: string
        pattern: '.*'

and a mapping

openapi-processor-spring: v2

options:
  package-name: generated
  bean-validation: true

map:
  types:
  - type: array => java.util.List

did not generate the javax.validation.constraints.Pattern import.

package generated.api;

import annotation.Mapping;
import annotation.Parameter;
import java.util.List;
import javax.validation.constraints.Pattern;

public interface Api {

    @Mapping("/test")
    void getTest(@Parameter List<@Pattern(regexp = ".*") String> patternParam);

}

(ignore the @Mapping/@Parameter annotations, this is pseudo-code used by the integration tests)

dependency updates

  • updated openapi-processor-core to 2022.5 (was 2022.4)