用于自定义响应的 Swagger 注释？

Question

像这样设置自定义响应：

public class CustomResponse {
    private int id;
    private String productName;
    private int quantity;
    private double price;

    // Constructor & along with Getters & Setters

}

我的 ProductController 中的 Swagger：

@RestController
@RequestMapping("/api/v1")
public class ProductController {

    @ApiOperation(httpMethod = "GET", 
                  value = "Retrieves reesults based on specific values set in the request parameters.", 
                  notes = "Sends back query results in JSON format after being processed.", 
                  produces = "application/json")
    @ApiResponses(value = { 
                        @ApiResponse(code = 200, message = "Successful GET command", response = CustomResponse.class),
                        @ApiResponse(code = 400, message = "Bad Request"),
                        @ApiResponse(code = 404, message = "Entity Not Found"), 
                        @ApiResponse(code = 500, message = "Internal Server Error") 
                        })
    @RequestMapping(value = "/products", method = RequestMethod.GET, produces="application/json" )
    public ResponseEntity<Object> getQueryResults(@ApiParam(value = "productName", required = true) @RequestParam(value = "productName") String productName) throws IOException {
        // Implementation details
    }
}

我的pom.xml:

    <!-- Swagger -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.6.1</version>
        <scope>compile</scope>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.6.1</version>
        <scope>compile</scope>
    </dependency>

当我启动我的网络服务并打开 Swagger 的 UI 时，我看到了 CustomResponse 的模型和示例值...

问题：

如何描述/记录 Swagger 中 CustomRepsonse 的各个属性？意思是，是否有 Swagger 注释来描述 CustomResponse 的每个字段？
在示例值中，有没有一种方法可以用实际的硬编码数据记录属性？

现在，它在示例值中显示如下：

{ "id" : 0, "productName" : "string","quantity" : 0, "price" : 0.00 }

Answer 1

How can I describe / document the individual attributes of the CustomRepsonse inside the Swagger? Meaning, is there a Swagger annotation to describe each field of the CustomResponse?

请注意注释 @io.swagger.annotations.ApiModelProperty - 它应该可以帮助您为 customResponse

添加文档

public class CustomResponse {
    private int id;
    @io.swagger.annotations.ApiModelProperty(value = "my super product name")
    private String productName;
    @io.swagger.annotations.ApiModelProperty(allowableValues = "1,5,10,25,50")
    private int quantity;
    private double price;

    // Constructor & along with Getters & Setters

}

In the Example Value, is there a way I can also document the attributes with actual hardcoded data?

当然可以为ApiParam指定默认值。我认为没有办法通过 CustomResponse 字段的 swagger 注释指定默认数据。部分您可以使用注释 @io.swagger.annotations.ApiModelProperty.

满足您的需求

您可以使用 swagger 为 CustomResponse 定义网络文档，但默认值将在 class 级别（构造函数或字段声明）中默认指定。为了使其更加灵活，我更喜欢在配置异常处理程序的地方使用 @ControllerAdvice，在这里我有机会映射 code 对应的异常并为我的自定义响应指定值（默认值）。

正如我在您的 swagger 文档中看到的，您已经覆盖了 code - 默认 message 映射。要使其正常工作，它会很有用 to change some configuration（请注意 .useDefaultResponseMessages(false) 并关注负责此事的行）。

用于自定义响应的 Swagger 注释？

Swagger Annotations for Customizing Responses?

java

swagger

swagger-ui

springfox