如何添加一个例子在@ApiResponse与Swagger?

Question

我想在我的方法中添加一个带有Swagger的示例，我尝试了一些事情，但它们不起作用。

我有我的接口，在那里我定义了方法:

@Api(value = "test API")
@RequestMapping("/api/v1/product")
public interface TestController {
@ApiOperation(
value = "Service that return a Product",
notes = "This service returns a Product by the ID",
nickname = "getProductById",
response = ProductResponse.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "The request has succeeded.", response = ProductResponse.class),
@ApiResponse(code = 500, message = "Internal server error.", response = ProductResponse.class) })
@GetMapping(
value = "/productById",
produces = { "application/json" }
)
ResponseEntity<ProductResponse> getProductById(@RequestParam(value = "productId", required = true) String productId);

ProductResponse类如下:

@Getter
@Setter
@AllArgsConstructor
public class ProductResponse {
private Product product;
private CustomException customException;
}

Product类如下:

@Getter
@Setter
@AllArgsConstructor
public class Product {
@JsonProperty("id")
private String id;
@JsonProperty("productName")
private String productName;
@JsonProperty("productDescription")
private String productDescription;
@JsonProperty("unitPrice")
private Double unitPrice;

CustomException类如下:

@Getter
public class CustomException {
private final String message;
private final String errorCode;
private final String errorType;
private final Exception exceptionDetail;

public CustomException(String message, String errorCode, String errorType, Exception exceptionDetail) {
this.message = message;
this.errorCode = errorCode;
this.errorType = errorType;
this.exceptionDetail = exceptionDetail;
}

当响应为200时，响应如下:

{
"product": {
"id": "12345",
"productName": "Product name",
"productDescription": "This is a description",
"unitPrice": 3.25
},
"customException": null
}

但是当响应是500时，响应是这样的:

{
"product": "null,",
"customException": {
"message": "/ by zero",
"errorCode": "500",
"errorType": "Internal server error",
"exceptionDetail": null,
"cause": null,
"stackTrace": [
{
"classLoaderName": "app",
"moduleName": null,
"moduleVersion": null,
"methodName": "getProductById",
"fileName": "TestControllerImpl.java",
"lineNumber": 33,
"className": "com.myproject.testmicroservice.controller.impl.TestControllerImpl",
"nativeMethod": false
}
]
}
}

如何在@ApiResponse注释中添加自定义示例?

Answer 1

您可能错过了@Operation注释，其中您放入了@ApiResponse。

的例子:

import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.Operation;
@Operation(responses = {
@ApiResponse(responseCode = "200", content = @Content(examples = {
@ExampleObject(name = "getUserAttribute",
summary = "Retrieves a User's attributes.",
description = "Retrieves a User's attributes.",
value = "[{"value": ["area1", "area2", "area3"], "key":"GENERAL_AREAS"}, {"value":"933933933", "key":"FONyE"}]")
}, mediaType = MediaType.APPLICATION_JSON_VALUE))})
public ResponseEntity<List<UserPreferenceDto>> getUserPreferenceByCode(
@Pattern(regexp = "\w+") @PathVariable String userCode, @Parameter(hidden = true) Pageable pageable) {
...
}

Answer 2

晚上好，希望你一切都好。在你描述的情况下，我会这样做

@ApiResponses(value = { 
@ApiResponse(responseCode = "200", description = "Found the book", 
content = { @Content(mediaType = "application/json", 
schema = @Schema(implementation = Book.class)) }),
@ApiResponse(responseCode = "400", description = "Invalid id supplied", 
content = @Content),

所描述的方法在这里解释。我认为这第九段。在您的案例中，使用@Operation和@ApiResponses生成文档是特别有趣的。我希望这对你有帮助，祝你晚安

Answer 3

您可以尝试这样做。在你的控制器中，你已经有@ApiResponses注释。您需要做的是将@ApiModel添加到Product类中，然后添加

@ApiModelProperty(notes = "Your comments", required = true, example = "example value")

到Product类的成员，即ProductResponse和CustomException。您需要验证的一件事是，是否可以在自定义对象(如ProductResponse和CustomException)上设置@ApiModelProperty。如果没有，则需要将@ApiModelProperty设置为1级深。

如本文所示，示例从模型属性自动填充到响应。

PS:到目前为止，我还没有一个swagger项目的设置，所以只能在理论上帮助你。

Answer 4

可能是这个迟来的答案，但如果有人需要它，您可以在@Operation

中添加requestBody描述和内容类型。

@io.swagger.v3.oas.annotations.Operation(summary = "", description = "",
requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE)))