如何注释 DTO 以使其显示在 SwaggerUI 架构中？

Question

我有一个带有@RequestBodyDTO 的控制器。我需要显示 DTO 的架构，而不是stringSwagger 中 RequestBody 架构中的默认架构。

通过在 API 之上使用 @Operation 并在其中使用 @Parameter，我已经能够在两个地方描述 DTO

并填写示例（参见代码）。我已经尝试@Schema过@Operation（在 requestBody 下）和@Parameter注释。前者抛出 NPE，后者不做任何改变，并针对 DTO 本身中的对应注释进行了各种尝试。

样品控制器

@RequestMapping(value = "/{myPathVar}", method = RequestMethod.POST)
@Operation(summary = "Create something.", 
    parameters = { @Parameter(in = ParameterIn.PATH, name = "myPathVar", description = "Some path variable. Swagger uses this description.") },             
    requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
        description = "My description here.", 
        content = @Content(examples = @ExampleObject("{\"A\" : \"a\",\"B\" : \"{\"b\" : \"foo\", \"bb\" : \"bar\"}"))))
@ApiResponse(content = @Content(schema = @Schema(implementation = MyReturningType.class)))
public MyReturningType doSomethingCool(
    @Parameter(description = "Some description Swagger ignores.", example = "123") @PathVariable(value = "myPathVar") int myPathVar,
    @Parameter(description = "My other description here.", schema = @Schema(implementation = MyDto.class)) @RequestBody MyDto dto) {
    // do something cool
}

示例 DTO

// Do I need certain annotations here?
public class MyDto {
    // What annotation goes here? @Parameter, @JsonProperty, @Schema, something else?
    private int someInt;
    private String someString;
    private Object someObject;
}

我需要什么注释组合才能在 DTO 中正确标记 DTO 架构，然后从控制器引用此架构，以便在 SwaggerUI 中填充架构字段？

Answer 1

该问题可能是由于 DTO 中的字段具有私有可见性，并且从您共享的代码来看，它们看起来没有可用的 getter 和 setter。

请参阅下面的示例，了解如何完成此操作的工作示例

控制器

// Using the specific mapping annotation will keep the code clean
@PostMapping("/{myPathVar}")

// The below annotation describes the operation
@Operation(
    summary = "Brief description of the operation",
    description = "Detailed description of the operation")

// Describe the possible responses next. Prefer using @ApiResponses for multiple response
@ApiResponse(

    // specify the http response code
    responseCode = "201",

    // some description. Maybe use the corresponding http response code's description
    description = "Created",

    // describe the content that will be returned for this response code
    content = @Content(
        // optionally, specify the media type for the response here as shown in the below code
         mediaType = MediaType.APPLICATION_JSON_VALUE,
        // specify the implementation of the response DTO here
        schema = @Schema(implementation = Void.class)))

public Void doSomethingCool(

    // Use @Parameter for @PathVariable and @RequestVariable
    @Parameter(description = "Description for path/request-parameter here")
    @PathVariable(value = "myPathVar")
        int myPathVar,

    // Both these @RequestBody annotations are mandatory.
    @io.swagger.v3.oas.annotations.parameters.RequestBody(
        description = "Controller-level model description here")
    @org.springframework.web.bind.annotation.RequestBody
        TestDTO dto) {
  // ... do some cool stuff here
  return null;
}

数据传输组织

@Schema(description = "Model-level description here")
public class TestDTO {

  @Schema(description = "Field-level description here")
  private int someInt;

  @Schema(description = "Another Field-level description here")
  private String someString;

  @Schema(description = "Yet another Field-level description here")
  private Object someObject;

  // all getters and setters here

}

这将为您提供如下输出