SwaggerUI响应示例与JSON媒体类型不起作用。

huangapple go评论75阅读模式
英文:

SwaggerUI Response Examples do not work with mediaType JSON

问题

似乎SwaggerUI存在一个bug,因为一旦我将@ExamplePropertymediaType设置为application/json,示例值就为空,如下所示:

SwaggerUI响应示例与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:

SwaggerUI响应示例与JSON媒体类型不起作用。

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 @ApiResponseexample? 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中使用producesconsumes,因为它是无用的。

SwaggerUI响应示例与JSON媒体类型不起作用。

英文:

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 = &quot;/predict&quot;, produces = &quot;application/json&quot;, consumes = &quot;application/json&quot;)

I give you a concrete example with my methods:

@ApiOperation(value = &quot;Sends a request to the AiController to predict the request&quot;, response =
			CatOrDogResponse.class, authorizations = @Authorization(value = &quot;Bearer&quot;))
	@ApiResponses(value = {@ApiResponse(code = 200, message = &quot;Successfully retrieved predictions&quot;),
			@ApiResponse(code = 401, message = &quot;You are not authorized to send a request&quot;), @ApiResponse(code = 403,
			message = &quot;Accessing the resource you were trying to reach is forbidden&quot;), @ApiResponse(code = 404,
			message = &quot;The resource you were trying to reach is not found&quot;)})
	@PostMapping(value = &quot;/predict&quot;, produces = &quot;application/json&quot;, consumes = &quot;application/json&quot;)
	public Mono&lt;CatOrDogResponse&gt; predict(@RequestHeader HttpHeaders headers, @ApiParam(name = &quot;Cat or Dog Prediction &quot;
			+ &quot;Request&quot;, value = &quot;Parameters for predicting whether an image or multiple images is/are a cat or dog&quot;) @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 = &quot;Cat or Dog response&quot;, description = &quot;Response of the prediction whether it&#39;s a cat or dog&quot;)
@Data
public class CatOrDogResponse {

	@ApiModelProperty(value = &quot;Images to predict&quot;, example = &quot;cat&quot;)
	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.

SwaggerUI响应示例与JSON媒体类型不起作用。

huangapple
  • 本文由 发表于 2020年8月28日 23:32:26
  • 转载请务必保留本文链接:https://go.coder-hub.com/63636821.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定