Блог

Допустим, у меня есть Spring Boot REST API со следующей конечной точкой и определенными моделями (для краткости параметры получения / установки опущены)

 @JsonTypeInfo( property = "type", include = JsonTypeInfo.As.PROPERTY, use = JsonTypeInfo.Id.NAME )
@JsonSubTypes( { @JsonSubTypes.Type( FooWidget.class ), @JsonSubTypes.Type( BarWidget.class ) } )
public interface Widget {}

public class BarWidget implements Widget { private String bar; }

public class FooWidget implements Widget { private String foo; }

public class WidgetGroup
{
    private List<Widget> widgets;
}

@RestController
public class WidgetController
{
    @PostMapping( "/widgets" )
    public void createWidgets( @RequestBody WidgetGroup widgets )
    {
    }
}
  

Возможно ли выразить это в спецификации OpenAPI, чтобы генератор мог оба

• воспроизведите приведенный выше код в виде заглушек сервера и моделей
• создайте клиент Javascript, который правильно представлял модели и API

Настроив это и попробовав springdoc и springfox сгенерировать мне спецификацию из кода, я не смог отменить процесс — приведенный выше код генерирует следующую спецификацию через Springdoc:

 openapi: 3.0.1
info:
  title: OpenAPI definition
  version: v0
servers:
  - url: 'http://localhost:8080'
    description: Generated server url
paths:
  /widgets:
    post:
      tags:
        - widget-controller
      operationId: createWidgets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WidgetGroup'
        required: true
      responses:
        '200':
          description: OK
components:
  schemas:
    BarWidget:
      type: object
      allOf:
        - $ref: '#/components/schemas/Widget'
        - type: object
          properties:
            bar:
              type: string
    FooWidget:
      type: object
      allOf:
        - $ref: '#/components/schemas/Widget'
        - type: object
          properties:
            foo:
              type: string
    Widget:
      required:
        - type
      type: object
      properties:
        type:
          type: string
      discriminator:
        propertyName: type
    WidgetGroup:
      type: object
      properties:
        widgets:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/BarWidget'
              - $ref: '#/components/schemas/FooWidget'
  

При использовании генераторов Java и Javascript информация о наследовании, похоже, теряется и генерируются нечетные классы, такие как «BarWidgetAllOf». Является ли это ограничением выразительности спецификации OAS или просто ограничением в реализациях генераторов (я пробовал оба с генераторами swagger-codegen и openapitools)?

Сгенерированная спецификация OpenAPI верна относительно вашего кода.

Это не ограничение, но должна быть генерация по умолчанию, которая обычно используется.

Если вы хотите более точный контроль над сгенерированной спецификацией, вы можете использовать аннотацию swagger @Schema (без использования JsonSubTypes), как объясняется в этих двух выпусках с примерами:

• https://github.com/swagger-api/swagger-core/issues/3046