英文:
SwaggerUI Response Examples do not work with mediaType JSON
问题
似乎SwaggerUI存在一个bug,因为一旦我将@ExampleProperty
的mediaType
设置为application/json
,示例值就为空,如下所示:
我已经尝试了几种方法,但都没有成功。根据这个问题看起来是一个常见的问题:https://github.com/springfox/springfox/issues/2352
我尝试了一个不太合理的解决方案(不起作用):
@ApiOperation(
value = "Sends a request to the AiController to predict the request",
produces = "application/json",
consumes = "application/json",
authorizations = @Authorization(value = "Bearer"))
@ApiResponses(
value = {
@ApiResponse(
code = 200,
message = "Successfully retrieved predictions",
examples =
@Example(
value = {@ExampleProperty(mediaType = "application/json", value = "test")}))
另一个也不起作用的解决方案:
@ApiOperation(
value = "Sends a request to the AiController to predict the request",
produces = "application/json",
consumes = "application/json",
authorizations = @Authorization(value = "Bearer"))
@ApiResponses(
value = {
@ApiResponse(
code = 200,
message = "Successfully retrieved predictions",
examples =
@Example(
value = {
@ExampleProperty(
mediaType = "application/json",
value = "{\"code\" : \"42\", \"message\" : \"Invalid ID supplied\"}")
}))
一个更简单的版本(也不起作用):
@ApiResponses(
value = {
@ApiResponse(
code = 200,
message = "Successfully retrieved predictions",
examples =
@Example(
value = {
@ExampleProperty(
value = "{'property': 'test'}",
mediaType = "application/json")
}))
但是只要我将mediaType
更改为没有特定类型,它就起作用了:
@ApiResponses(
value = {
@ApiResponse(
code = 200,
message = "Successfully retrieved predictions",
examples =
@Example({
@ExampleProperty(
mediaType = "*/*",
value = "{\"predictions\": [\"cat\"]}")
}))
输出为:
{
"predictions": ["cat"]
}
这几乎是我想要的,但缩进当然是错误的。
还有其他方法可以使用@ApiResponse
的示例吗?我不能在DTO中使用示例吗(?):
@ApiModel(
value = "Cat or Dog response",
description = "Response of the prediction whether it's a cat or dog")
@Data
public class CatOrDogResponse {
@ApiModelProperty(value = "Images to predict", example = "test", required = true)
private String[] predictions;
}
我使用的Spring Fox版本:
compile group: 'io.springfox', name: 'springfox-swagger2', version: '3.0.0'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '3.0.0'
compile group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
compile group: 'io.springfox', name: 'springfox-data-rest', version: '3.0.0'
compile group: 'io.springfox', name: 'springfox-bean-validators', version: '3.0.0'
英文:
It seems that there is a bug in SwaggerUI because as soon as I set the mediaType of @ExampleProperty
to application/json
the example value is empty as you can see here:
I've tried several ways but none is working. According to this it seems to be a popular problem: https://github.com/springfox/springfox/issuesW/2352
I've tried an unlogical solution (does not work):
@ApiOperation(
value = "Sends a request to the AiController to predict the request",
produces = "application/json",
consumes = "application/json",
authorizations = @Authorization(value = "Bearer"))
@ApiResponses(
value = {
@ApiResponse(
code = 200,
message = "Successfully retrieved predictions",
examples =
@Example(
value = {@ExampleProperty(mediaType = "application/json", value = "test")}))
Another one (also not working):
@ApiOperation(
value = "Sends a request to the AiController to predict the request",
produces = "application/json",
consumes = "application/json",
authorizations = @Authorization(value = "Bearer"))
@ApiResponses(
value = {
@ApiResponse(
code = 200,
message = "Successfully retrieved predictions",
examples =
@Example(
value = {
@ExampleProperty(
mediaType = "application/json",
value = "{\"code\" : \"42\", \"message\" : \"Invalid ID supplied\"}")
}))
A simpler version (not working):
@ApiResponses(
value = {
@ApiResponse(
code = 200,
message = "Successfully retrieved predictions",
examples =
@Example(
value = {
@ExampleProperty(
value = "{'property': 'test'}",
mediaType = "application/json")
}))
But as soon that I change the mediaType to don't have a specific type it works:
@ApiResponses(
value = {
@ApiResponse(
code = 200,
message = "Successfully retrieved predictions",
examples =
@Example({
@ExampleProperty(
mediaType = "*/*",
value = "{\n\"predictions\": [ \n \"cat\" \n]\n}")
}))
Output is:
{
"predictions": [
"cat"
]
}
Thats nearly what I want to have but of course the indentation is wrong.
Is there any other way to do an @ApiResponse
example? Can't I give an example with my DTO (?):
@ApiModel(
value = "Cat or Dog response",
description = "Response of the prediction whether it's a cat or dog")
@Data
public class CatOrDogResponse {
@ApiModelProperty(value = "Images to predict", example = "test", required = true)
private String[] predictions;
}
My used Spring Fox versions:
compile group: 'io.springfox', name: 'springfox-swagger2', version: '3.0.0'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '3.0.0'
compile group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
compile group: 'io.springfox', name: 'springfox-data-rest', version: '3.0.0'
compile group: 'io.springfox', name: 'springfox-bean-validators', version: '3.0.0'
答案1
得分: 0
最后答案很简单。我在GitHub上找到了这个:https://github.com/springfox/springfox/issues/2538#issuecomment-637265748
这个错误应该已经修复了,但实际上还没有修复。为了使响应的示例值能够正常工作,需要调整REST类型的注释:
@PostMapping(value = "/predict", produces = "application/json", consumes = "application/json")
我给你一个使用我的方法的具体示例:
@ApiOperation(value = "Sends a request to the AiController to predict the request", response =
CatOrDogResponse.class, authorizations = @Authorization(value = "Bearer"))
@ApiResponses(value = {@ApiResponse(code = 200, message = "Successfully retrieved predictions"),
@ApiResponse(code = 401, message = "You are not authorized to send a request"), @ApiResponse(code = 403,
message = "Accessing the resource you were trying to reach is forbidden"), @ApiResponse(code = 404,
message = "The resource you were trying to reach is not found")})
@PostMapping(value = "/predict", produces = "application/json", consumes = "application/json")
public Mono<CatOrDogResponse> predict(@RequestHeader HttpHeaders headers, @ApiParam(name = "Cat or Dog Prediction "
+ "Request", value = "Parameters for predicting whether an image or multiple images is/are a cat or dog") @Valid @RequestBody CatOrDogRequest catOrDogRequest) {
...
}
重要的是,你像我这样在@ApiOperation
中定义响应类:response = CatOrDogResponse.class
在响应类中,你为响应定义示例值:
@ApiModel(value = "Cat or Dog response", description = "Response of the prediction whether it's a cat or dog")
@Data
public class CatOrDogResponse {
@ApiModelProperty(value = "Images to predict", example = "cat")
private String[] predictions;
}
现在的变化是最终自动将响应类型声明为application/json
而不是*/*
。正确的缩进会自动工作。正如你所见,我不再在@ApiOperation
中使用produces
和consumes
,因为它是无用的。
英文:
In the end the answer is easy. I found this on GitHub: https://github.com/springfox/springfox/issues/2538#issuecomment-637265748
The bug should be fixed but it's still not fixed. To get the example value working for responses the annotation of the REST type needs to be adjusted:
@PostMapping(value = "/predict", produces = "application/json", consumes = "application/json")
I give you a concrete example with my methods:
@ApiOperation(value = "Sends a request to the AiController to predict the request", response =
CatOrDogResponse.class, authorizations = @Authorization(value = "Bearer"))
@ApiResponses(value = {@ApiResponse(code = 200, message = "Successfully retrieved predictions"),
@ApiResponse(code = 401, message = "You are not authorized to send a request"), @ApiResponse(code = 403,
message = "Accessing the resource you were trying to reach is forbidden"), @ApiResponse(code = 404,
message = "The resource you were trying to reach is not found")})
@PostMapping(value = "/predict", produces = "application/json", consumes = "application/json")
public Mono<CatOrDogResponse> predict(@RequestHeader HttpHeaders headers, @ApiParam(name = "Cat or Dog Prediction "
+ "Request", value = "Parameters for predicting whether an image or multiple images is/are a cat or dog") @Valid @RequestBody CatOrDogRequest catOrDogRequest) {
...
}
Important is that you define the response class in the @ApiOperation
like me: response = CatOrDogResponse.class
In the response class you define the example value for the response:
@ApiModel(value = "Cat or Dog response", description = "Response of the prediction whether it's a cat or dog")
@Data
public class CatOrDogResponse {
@ApiModelProperty(value = "Images to predict", example = "cat")
private String[] predictions;
}
What changed now is that finally automatically the response type is declared as application/json
instead of */*
. The correct indentation works automatically. And as you can see I'm not using produces
and consumes
in the @ApiOperation
anymore because it's useless.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。
评论