SpringDoc 生成具有多种媒体类型的 OpenApi 规范

如何解决SpringDoc 生成具有多种媒体类型的 OpenApi 规范

在我的 Spring 项目中，我使用 Springdoc 生成 OpenApiSpecification 文档。 我用这些注释创建了我的 Api。我想要具有不同媒体类型的相同端点 url 来处理不同对象的 POST。

@Validated
@Tag(name = "Calendar",description = "Api for Calendar resource")
public interface CalendarApi {


    @Operation(summary = "Add an appointment to the calendar",description = "Add an appointment to the calendar",tags = {"appointment"})
    @ApiResponses(value = {
            @ApiResponse(responseCode = "201",description = "Successful operation",content = @Content(mediaType = "application/json+widget",schema = @Schema(implementation = AppointmentWidgetDto.class))),@ApiResponse(responseCode = "400",description = "Invalid input")
    })
    @PostMapping(value = "/appointments",consumes = "application/json+widget")
    ResponseEntity<Appointment> saveFromWidget(@Parameter(description = "The new appointment to save",required = true) @Valid @RequestBody AppointmentWidgetDto appointmentDto);

    @Operation(summary = "Add an appointment to the calendar",content = @Content(mediaType = "application/json",schema = @Schema(implementation = Appointment.class))),consumes = MediaType.APPLICATION_JSON_VALUE)
    ResponseEntity<Appointment> save(@Parameter(description = "The new appointment to save",required = true) @Valid @RequestBody Appointment appointmentDto);

}

生成的 Open Api Spec 文档为：

  /api/v1/appointments:
    post:
      tags:
        - Calendar
      summary: Add an appointment to the calendar
      description: Add an appointment to the calendar
      operationId: save_1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Appointment'
          application/json+widget:
            schema:
              $ref: '#/components/schemas/AppointmentWidgetDto'
        required: true
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '400':
          description: Invalid input
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Appointment'

我有几个问题：

• 端点名称没有意义 (save_1)

• 当我使用 Open Api 生成器根据此规范生成 Angular 客户端时，我有一些警告会阻止生成这两种方法。

  [警告] 在 OAS 的“内容”部分找到多个架构，仅返回第一个 (application/json) [警告] 发现多个 MediaType，仅使用第一个

我知道此问题已打开 (https://github.com/OpenAPITools/openapi-generator/issues/3990)。 有没有办法允许在同一个端点 url 中发布两个不同的主体并使用 OpenApi 生成器为不同的语言/平台创建客户端？

====== 更新 ========

这是 AppointmentWidgetDTO：

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@SuperBuilder
public class AppointmentWidgetDto implements Serializable {
    @NotNull(message = "{appointment.store.missing}")
    @JsonDeserialize(using = StoreUriDeserializer.class)
    private Store store;

    @NotNull(message = "{appointment.title.missing}")
    @Size(max = 255)
    private String title;

    @Lob
    @Size(max = 1024)
    private String description;

    @Size(max = 50)
    private String type;

    @Size(max = 50)
    private String icon;

    @NotNull(message = "{appointment.startdate.missing}")
    private Instant startDate;

    @NotNull(message = "{appointment.enddate.missing}")
    private Instant endDate;

    @JsonDeserialize(using = ContactUriDeserializer.class)
    private Contact contact;

    @NotBlank(message = "{appointment.contactname.missing}")
    private String contactName;

    @NotBlank(message = "{appointment.email.missing}")
    @Email
    private String contactEmail;

    @NotBlank(message = "{appointment.phone.missing}")
    @PhoneNumber
    private String contactPhone;

}

这是约会：

@ScriptAssert(lang = "javascript",script = "_.startDate.isBefore(_.endDate)",alias = "_",reportOn = "endDate",message = "{appointment.invalid.end.date}")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@SuperBuilder
public class Appointment extends AbstractEntity {


    @NotNull(message = "{appointment.store.missing}")
    @JsonDeserialize(using = StoreUriDeserializer.class)
    @ManyToOne(fetch = FetchType.LAZY,optional = false)
    @JoinColumn(name = "store_id",updatable = false)
    private Store store;

    @NotNull
    @Size(max = 255)
    @Column(nullable = false,length = 255)
    private String title;

    @Lob
    @Size(max = 1024)
    @Column(length = 1024)
    private String description;

    @Size(max = 30)
    @Column(length = 30)
    private String color;

    @Size(max = 50)
    @Column(length = 50)
    private String type;

    @Size(max = 50)
    @Column(length = 50)
    private String icon;

    @Size(max = 255)
    @Column(length = 255)
    private String location;

    @NotNull
    @Column(nullable = false)
    private Instant startDate;

    @NotNull
    @Column(nullable = false)
    private Instant endDate;

    @Builder.Default
    @NotNull
    @Column(nullable = false,columnDefinition = "BIT DEFAULT 0")
    private boolean allDay = false;


    @JoinColumn(name = "contact_id")
    @JsonDeserialize(using = ContactUriDeserializer.class)
    @ManyToOne(fetch = FetchType.LAZY)
    private Contact contact;

    private String contactName;

    @Email
    private String contactEmail;

    @PhoneNumber
    private String contactPhone;

   
    @JoinColumn(name = "agent_id")
    @JsonDeserialize(using = AgentUriDeserializer.class)
    @ManyToOne(fetch = FetchType.LAZY)
    private Agent agent;

   
    private String agentName;

    @Builder.Default
    @JsonProperty(access = JsonProperty.Access.READ_ONLY)
    @NotNull
    @Column(nullable = false)
    @Enumerated(EnumType.STRING)
    private AppointmentStatus status = AppointmentStatus.VALID;

解决方法

使用 OpenAPI 3，您不能对同一路径进行多次操作。

您将只有一个端点和一个 OpenAPI 描述。

您可以做的是定义 @Operation 注释在方法之一的顶部，您可以在其中添加所有其他方法的合并 OpenAPI 描述的 OpenAPI 文档作为好吧，然后在其他人上添加 @Hidden 注释。

或者您可以定义两个不同的组：对于您使用标头匹配过滤的每个组，headersToMatch Bean 的选项 GroupedOpenApi。