what is openapi-processor?

openapi-processor is a small framework to process OpenAPI yaml files. Currently, openapi-processor provides java code generation for Spring Boot, Micronaut and conversion to json.

It does support gradle and maven to run any openapi-processor as part of the build process.

See the documentation for more. There is also a playground to preview the processors.

what is new?

See the release notes for the full details (it is the same for spring & micronaut).

Apart from a couple of bug fixes and improvements for multipart requests and bean-validations, openapi-processor is now able to automatically add a suffix to the generated model classes.

This is enabled by configuring the model-name-suffix in the mapping.yaml:

<span>openapi-processor-mapping</span><span>:</span> <span>v2</span>
<span>options</span><span>:</span>
  <span>package-name</span><span>:</span> <span>io.openapiprocessor.sample</span>
  <span>model-name-suffix</span><span>:</span> <span>Resource</span> <span># or Dto or ...</span>
<span>openapi-processor-mapping</span><span>:</span> <span>v2</span>

<span>options</span><span>:</span>
  <span>package-name</span><span>:</span> <span>io.openapiprocessor.sample</span>
  <span>model-name-suffix</span><span>:</span> <span>Resource</span> <span># or Dto or ...</span>
openapi-processor-mapping: v2

options:
  package-name: io.openapiprocessor.sample
  model-name-suffix: Resource # or Dto or ...

Enter fullscreen mode Exit fullscreen mode

The model-name-suffix option sets a suffix that is automatically appended to all generated model and enum classes.

The suffix helps to

• avoid duplicate class names in generated code and normal code

• makes it easier to recognize which role or in which context a class is used. Is it a data transfer class or is it a domain class?

• keeps the suffix “noise” out of the OpenAPI description

Usually you will separate the classes by putting them in different packages. This helps to distinguish the classes, but when both are used in the same code, i.e. when converting one format to the other, it is a lot easier to distinguish them by their class name instead of their package name.

If a schema name from the OpenAPI description already ends with the model-name-suffix, the processor will not append the suffix. This allows to migrate an existing api with a suffix in the API to model-name-suffix step by step.
Example:

OpenAPI

<span>paths</span><span>:</span>
  <span>/foo</span><span>:</span>
    <span>get</span><span>:</span>
      <span>responses</span><span>:</span>
        <span>'</span><span>200'</span><span>:</span>
          <span>description</span><span>:</span> <span>the foo result</span>
          <span>content</span><span>:</span>
            <span>application/json</span><span>:</span>
              <span>schema</span><span>:</span>
                <span>$ref</span><span>:</span> <span>'</span><span>#/components/schemas/Foo'</span> <span># (1)</span>
<span>components</span><span>:</span>
  <span>schemas</span><span>:</span>
    <span>Foo</span><span>:</span>
      <span>type</span><span>:</span> <span>object</span>
      <span>properties</span><span>:</span>
        <span>nested</span><span>:</span>
          <span>$ref</span><span>:</span> <span>'</span><span>#/components/schemas/BarResource'</span> <span># (1)</span>
    <span>BarResource</span><span>:</span>
      <span>type</span><span>:</span> <span>object</span>
      <span>properties</span><span>:</span>
        <span>prop</span><span>:</span>
          <span>type</span><span>:</span> <span>string</span>
<span>paths</span><span>:</span>
  <span>/foo</span><span>:</span>
    <span>get</span><span>:</span>
      <span>responses</span><span>:</span>
        <span>'</span><span>200'</span><span>:</span>
          <span>description</span><span>:</span> <span>the foo result</span>
          <span>content</span><span>:</span>
            <span>application/json</span><span>:</span>
              <span>schema</span><span>:</span>
                <span>$ref</span><span>:</span> <span>'</span><span>#/components/schemas/Foo'</span> <span># (1)</span>

<span>components</span><span>:</span>
  <span>schemas</span><span>:</span>

    <span>Foo</span><span>:</span>
      <span>type</span><span>:</span> <span>object</span>
      <span>properties</span><span>:</span>
        <span>nested</span><span>:</span>
          <span>$ref</span><span>:</span> <span>'</span><span>#/components/schemas/BarResource'</span> <span># (1)</span>

    <span>BarResource</span><span>:</span>
      <span>type</span><span>:</span> <span>object</span>
      <span>properties</span><span>:</span>
        <span>prop</span><span>:</span>
          <span>type</span><span>:</span> <span>string</span>
paths:
  /foo:
    get:
      responses:
        '200':
          description: the foo result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Foo' # (1)

components:
  schemas:

    Foo:
      type: object
      properties:
        nested:
          $ref: '#/components/schemas/BarResource' # (1)

    BarResource:
      type: object
      properties:
        prop:
          type: string

Enter fullscreen mode Exit fullscreen mode

mapping.yaml

<span>openapi-processor-mapping</span><span>:</span> <span>v2</span>
<span>options</span><span>:</span>
  <span>package-name</span><span>:</span> <span>io.openapiprocessor.sample</span>
  <span>model-name-suffix</span><span>:</span> <span>Resource</span> <span># (2)</span>
<span>openapi-processor-mapping</span><span>:</span> <span>v2</span>

<span>options</span><span>:</span>
  <span>package-name</span><span>:</span> <span>io.openapiprocessor.sample</span>
  <span>model-name-suffix</span><span>:</span> <span>Resource</span> <span># (2)</span>
openapi-processor-mapping: v2

options:
  package-name: io.openapiprocessor.sample
  model-name-suffix: Resource # (2)

Enter fullscreen mode Exit fullscreen mode

Java

<span>// interface</span>
<span>public</span> <span>interface</span> <span>Api</span> <span>{</span>
    <span>@Mapping</span><span>(</span><span>"/foo"</span><span>)</span>
    <span>FooResource</span> <span>getFoo</span><span>();</span> <span>// (3)</span>
<span>}</span>
<span>// pojos</span>
<span>public</span> <span>class</span> <span>FooResource</span> <span>{</span> <span>// (3)</span>
    <span>// ...</span>
    <span>@JsonProperty</span><span>(</span><span>"nested"</span><span>)</span>
    <span>private</span> <span>BarResource</span> <span>nested</span><span>;</span>
    <span>// ...</span>
<span>}</span>
<span>public</span> <span>class</span> <span>BarResource</span> <span>{</span> <span>// (4)</span>
    <span>// ...</span>
<span>}</span>
<span>// interface</span>
<span>public</span> <span>interface</span> <span>Api</span> <span>{</span>

    <span>@Mapping</span><span>(</span><span>"/foo"</span><span>)</span>
    <span>FooResource</span> <span>getFoo</span><span>();</span> <span>// (3)</span>

<span>}</span>

<span>// pojos</span>
<span>public</span> <span>class</span> <span>FooResource</span> <span>{</span> <span>// (3)</span>

    <span>// ...</span>

    <span>@JsonProperty</span><span>(</span><span>"nested"</span><span>)</span>
    <span>private</span> <span>BarResource</span> <span>nested</span><span>;</span>

    <span>// ...</span>
<span>}</span>

<span>public</span> <span>class</span> <span>BarResource</span> <span>{</span> <span>// (4)</span>

    <span>// ...</span>
<span>}</span>
// interface
public interface Api {

    @Mapping("/foo")
    FooResource getFoo(); // (3)

}

// pojos
public class FooResource { // (3)

    // ...

    @JsonProperty("nested")
    private BarResource nested;

    // ...
}

public class BarResource { // (4)

    // ...
}

Enter fullscreen mode Exit fullscreen mode

1. a schema name without suffix
2. the suffix configuration
3. the class name of the Foo schema got the configured Resource suffix
4. the class name of the BarResource is identical to the original schema name. Since the existing suffix is equal to model-name-suffix it is ignored. Otherwise, This prevents funny class names like BarResourceResource.

That’s it.

原文链接：openapi-processor-spring 2021.4 & micronaut 2021.2