<Spring Boot / Springfox> Swagger UI 未显示示例值和模型

Question

我使用 Springfox 从 Spring Boot REST 控制器生成 Swagger API 规范。

我注意到一个问题，无法显示示例值/模型以进行响应。

作为一项调查，我检查了 http://localhost:8080/v2/api-docs 上的 JSON API 文档， 并将其转换为 YMAL 在 https://editor.swagger.io/ ，它也无法显示示例值/模型。 这似乎是由于模式没有正确引用模型对象（此处为“汽车”）引起的。

但是从Swagger的API文档（https://docs.swagger.io/swagger-core/v1.5.0/apidocs/io/swagger/annotations/ApiResponse.html#response()）来看，它说注释 @ApiResponse 的“response”属性应对应于规范的“schema”字段。

通过指定response =“Object.class”，Swagger UI 不应该相应地填充示例值/模型吗？

欢迎大家提出建议，如有错误配置/误解，请指正，非常感谢。

REST 控制器和注释：

@GetMapping(path = "/car")
@ApiOperation(value = "Get car by color.", response = Car.class)
@ApiParam(value = "Color of the car.", required = true)
@ApiResponses(value = { @ApiResponse(code = 200, message = "OK.", response = Car.class),
        @ApiResponse(code = 400, message = "Invalid color provided."),
        @ApiResponse(code = 404, message = "Car not found.") })
public ResponseEntity<Object> getCarByColor(@RequestParam String color) {
    return ResponseEntity.ok(testService.getCarByColor(color));
}

型号：

package com.example.demo.model;

import javax.validation.constraints.Max;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@ApiModel(value = "Car", description = "The model for car")
@Data
public class Car {
    @ApiModelProperty(notes = "Car ID.", example = "12345", required = false, position = 0)
    private Long id;

    @ApiModelProperty(notes = "Car name.", example = "Suzuki Swift 2020", required = true, position = 1)
    @NotNull
    @Max(value = 30, message = "Name can only have a maximum length of 30")
    private String name;

    @ApiModelProperty(notes = "Car color.", example = "blue", required = true, position = 2)
    @NotNull
    @Max(value = 30, message = "Color can only have a maximum length of 30")
    @Pattern(regexp = "^(blue|yellow)$", message = "Only blue or yellow color is allowed.")
    private String color;

    public Car(Long id, String name, String color) {
        this.id = id;
        this.name = name;
        this.color = color;
    }
}

Swagger 用户界面：

pom.xml 中的 Springfox 依赖：

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>

进行了以下更改以使用OAS3.0规范和注释，但仍然存在问题。它还在 Swagger UI 中给出错误。

REST 控制器和注释：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;

...
......

@GetMapping(path = "/car", produces = "application/json")
@Operation(summary = "Get car by color.", responses = {
        @ApiResponse(responseCode = "200", description = "OK.", content = {
                @Content(mediaType = "application/json", schema = @Schema(type = "object", implementation = Car.class)) }) })
public ResponseEntity<Object> getCarByColor(@RequestParam String color) {
    return ResponseEntity.ok(testService.getCarByColor(color));
}

型号：

package com.example.demo.model;

import javax.validation.constraints.Max;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@ApiModel(value = "Car", description = "The model for car")
@Schema
@Data
public class Car {
    @ApiModelProperty(notes = "Car ID.", example = "12345", required = false, position = 0)
    private Long id;

    @ApiModelProperty(notes = "Car name.", example = "Suzuki Swift 2020", required = true, position = 1)
    @NotNull
    @Max(value = 30, message = "Name can only have a maximum length of 30")
    private String name;

    @ApiModelProperty(notes = "Car color.", example = "blue", required = true, position = 2)
    @NotNull
    @Max(value = 30, message = "Color can only have a maximum length of 30")
    @Pattern(regexp = "^(blue|yellow)$", message = "Only blue or yellow color is allowed.")
    private String color;

    public Car(Long id, String name, String color) {
        this.id = id;
        this.name = name;
        this.color = color;
    }
}

Swagger 用户界面：

Answer 1

您可以使用

V3

模型覆盖

V2

模型。只需在您的

application.properties

中添加一个属性，您的

@ApiResponse

注释就应该可以正常工作。

springfox.documentation.swagger.use-model-v3=false

确保使用旧的

@ApiResponses

和

@ApiResponse

注释。 此问题已记录在https://github.com/springfox/springfox/issues/3503

Answer 2

在使用

springdoc-openapi-ui

(>=1.5.0) 的情况下，这是我的工作示例，用于在 SwaggerUI 的请求和响应部分中显示示例数据（如果它是 JSON 对象）。 希望它也能通过一些小的改变来适合您的情况。

@Operation(summary = "Send some JSON")
@ApiResponses(value = {
    @ApiResponse(
        responseCode = "200",
        description = "Success: our action has been completed",
        content = @Content(mediaType = "application/json",
        schema = @Schema(
            type = "SampleHttpResponseDto",
            example = "{\"status\":\"OK\",\"message\":\"sample OK answer\"}")))})
@PostMapping(value = "/resource", consumes = MediaType.APPLICATION_JSON_VALUE)
public SampleHttpResponseDto postRequest(
    @Parameter(
        name ="json",
        schema = @Schema(
            description = "additional description of the model",
            type = "string",
            example = "{\"status\":\"OK\",\"message\":\"message body\"}"))
    @RequestBody Map<String, Object> request
) {
  return new SampleHttpResponseDto(request.propert1, request.propert2);
}

要点：https://gist.github.com/antukhov/7dece86c6d16cc81bb6f83f47ffc0c8d

SwaggerUI

Answer 3

使用 swagger-2 注释对我有用，将

produces='application/json'

添加到

@GetMapping

或任何

@RequestMapping

。

Answer 4

Swagger 似乎只公开了我们在控制器层中公开的模型。要公开我们的内部模型/DTO，我们需要在 Docket bean 中配置其他模型才能公开它们。

@Bean
public Docket docket() {
    return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            .additionalModels(typeResolver.resolve(Car.class))
            .select()
            .apis(RequestHandlerSelectors.any()) 
            .paths(PathSelectors.any())
            .build();
}

其中 typeResolver 是 com.fasterxml.classmate.TypeResolver 类的实例，如果您已在项目中包含依赖项，则可以在提供的配置类中自动装配该类。