docs.openapiprocessor.io

Models

The processor will create simple POJOs classes for the object schemas used in the OpenAPI description. A POJO will only have (annotated) properties and get/set methods for its properties.

The following api describes two endpoints:

  • the first one /book-inline defines the response schema inline. This is interesting because the api does not provide a schema name.

  • the second one /book references a named schema.

openapi: 3.1.0
info:
  title: model example
  version: 1.0.0

paths:
  /book-inline:
    get:
      responses:
        '200':
          description: none
          content:
            application/json:
                schema:
                  type: object
                  properties:
                    isbn:
                      type: string
                    title:
                      type: string

  /book:
    get:
      responses:
        '200':
          description: none
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Book'

components:
  schemas:
    Book:
      type: object
      properties:
        isbn:
          type: string
        title:
          type: string

The second endpoint uses a schema with a name, so the processor can simply create a POJO using the name as the Java class name.

package generated.model;

import com.fasterxml.jackson.annotation.JsonProperty;

public class Book {

    @JsonProperty("isbn")
    private String isbn;

    @JsonProperty("title")
    private String title;

    public String getIsbn () {
        return isbn;
    }

    public void setIsbn (String isbn) {
        this.isbn = isbn;
    }

    public String getTitle () {
        return title;
    }

    public void setTitle (String title) {
        this.title = title;
    }

}

The first endpoint has no name, and the processor invents a name based on the endpoint description. In this case the name will be BookInlineResponse200. To create a unique name and avoid name collisions with other inline objects, it is created by concatenating:

  • the path of the endpoint, /book-inline is mapped to BookInline

  • Response, because it is an inline object described under responses:

  • 200, which is the http status code of the response

which is finally the bulky BookInlineResponse200.

Apart from the generated name it will have exactly the same content (i.e., properties and setter/getter) since the schema description is identical.

readOnly/writeOnly

Using readOnly/writeOnly on object schema properties

Foo:
  type: object
  properties:
    barRead:
      readOnly: true
      allOf:
        - $ref: '#/components/schemas/Bar'
    barWrite:
      writeOnly: true
      allOf:
        - $ref: '#/components/schemas/Bar'

will translate to @JsonProperty annotations with read-only or write-only access:

public class Foo {

    @JsonProperty(value = "barRead", access = JsonProperty.Access.READ_ONLY)
    private Bar barRead;

    @JsonProperty(value = "barWrite", access = JsonProperty.Access.WRITE_ONLY)
    private Bar barWrite;

   // ....
}