如何注释 DATA 以使其显示在 Swagger UI Schema 中？

Question

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

通过使用 API 上方的 @Operation 和内部的 @Parameter，我已经能够在两个地方描述 DTO

并填写示例（参见代码）。我在@Operation（在requestBody 下）和@Parameter 注释中尝试了@Schema。前者抛出一个 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 Schema，然后从控制器引用此 Schema，以便在 SwaggerUI 中填充 Schema 字段？

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;
}

DTO

@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

}

这将为您提供如下输出