如何注解DTO，使其显示在SwaggerUI模式中？

0h4hbjxa 于 2022-11-06 发布在其他

关注(0)|答案(2)|浏览(384)

我有一个带有@RequestBody DTO的控制器。我需要在Swagger的RequestBody模式中显示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模式，然后从控制器引用此模式，以便在SwaggerUI中填充模式字段？

swagger

来源：https://stackoverflow.com/questions/69210490/how-to-annotate-dto-so-that-it-shows-up-in-swaggerui-schema

2条答案

按热度按时间

0ejtzxu11#

这个问题可能是由于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

}

这将为您提供如下输出

赞(0）回复(0）举报 2022-11-06

mspsb9vt2#

我给你的dto做了如下注解。它对我很有效

@Schema(description = "User Dto")
@Data
public class UserDto {
  private int id;

  @JsonProperty
  private String email;

  @JsonProperty
  private String password;

  @JsonProperty
  private String firstName;

  @JsonProperty
  @Schema(description = "User Id")
  private String lastName;
}

赞(0）回复(0）举报 2022-11-06

我来回答

如何注解DTO，使其显示在SwaggerUI模式中？

2条答案

相关问题

热门标签

最新问答