Spring 启动 REST API 删除重复的响应主体

Question

所以我正在使用 springdoc-openapi-ui 并且我能够生成 API 可以使用 swagger UI.

但是，我注意到 swagger UI 中的所有响应代码都从 return 复制了响应代码 200 响应代码，这是我没有做的事情，是 q ui危险的误导。

如何禁用此行为？使用 Swagger2 不会产生此行为。我的方法使用 ResponseEntity 到 return 响应。这可能是个问题吗？

OpenApi30Config.java -- 打开文档配置文件

@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "${spring.application.name}",
                description = "${spring.application.name}'s official API documentation",
                version = "${spring.application.version}",
                contact = @Contact(name = "John Does Live", email = "does.john.live@whosebug.com"),
                license = @License(name = "Apache 2.0")
        ),
        security = @SecurityRequirement(name = AppConstants.API_SECURITY_REQUIREMENT_NAME)
)
@SecuritySchemes({
        @SecurityScheme(
                name = AppConstants.API_SECURITY_REQUIREMENT_NAME,
                in = SecuritySchemeIn.HEADER,
                type = SecuritySchemeType.APIKEY,
                description = "Provisioned API key",
                paramName = AppConstants.API_KEY_HEADER_NAME
        ),
        @SecurityScheme(
                name = "bearerToken",
                in = SecuritySchemeIn.HEADER,
                type = SecuritySchemeType.APIKEY,
                paramName = AppConstants.JWT_HEADER_NAME,
                description = "JWT token obtained after user authenticated with the server"
        )
})
@Profile("dev")
public class OpenApi30Config {
}

GeneralAPIResponses.java -- 要应用于所有控制器方法的注释。记录所有一般响应代码。

@Documented
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "Operation was successful"),
        @ApiResponse(responseCode = "401", description = "Invalid API key"),
        @ApiResponse(responseCode = "403", description = "Invalid JWT", content),
        @ApiResponse(responseCode = "500", description = "Internal server error")
})
public @interface GeneralAPIResponses {
}

SecuredRestAPIController.java -- 表明端点是安全的。

@SecurityRequirement(name = AppConstants.API_SECURITY_REQUIREMENT_NAME)
public interface SecuredRestAPIController {
}

BaseController.java -- 可扩展控制器

@Validated
public abstract class BaseController {
    protected final Logger LOG;

    protected BaseController() {
        LOG = LoggerFactory.getLogger(getClass());
    }

    protected String format(String format, Object... args) {
        return String.format(Locale.US, format, args);
    }
}

Foo.java

@RestController
@RequestMapping("/foo")
@Tag(name = "Foo", description = "Endpoint for handling all foo related operations.")
public class FooController extends BaseController implements SecuredRestAPIController {

    @PostMapping
    @Operation(
            description = "Add foo.",
            responses = {
                    @ApiResponse(responseCode = "409", description = "Foo with same phone number already exists.")
            })
    @GeneralAPIResponses
    ResponseEntity<FooActionResponse> addFoo(@Valid @RequestBody FooActionRequest request) {
        // ... logic
        return ResponseEntity.ok(new FooActionResponse(UUID.randomUUID(), LocalDateTime.now()));
    }

}

所有这一切之后，这就是我得到的：

还有这个。（注意 FooActionResponse 响应被复制到所有响应）我不希望有这个因为它会误导其他开发人员阅读文档。似乎所有状态代码 return 的内容都相同，而 API 却没有。

Answer 1

出现此问题是因为您没有为每个额外的回复指定 @Content。 SpringDoc 假定响应主体与您的注释方法相同。

如果您有错误响应的通用错误模型，您可以在内容部分指定它：

    @ApiResponses({
        @ApiResponse(responseCode = "401", description = "Invalid API key", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = ErrorModel.class))),
        @ApiResponse(responseCode = "403", description = "Invalid JWT", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = ErrorModel.class))),
        @ApiResponse(responseCode = "500", description = "Internal server error", content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, schema = @Schema(implementation = ErrorModel.class))),
    })

如果您只需要错误的描述，而不需要任何架构，则需要为响应指定一个空 @Content：

    @ApiResponses({
        @ApiResponse(responseCode = "401", description = "Invalid API key", content = @Content),
        @ApiResponse(responseCode = "403", description = "Invalid JWT", content = @Content),
        @ApiResponse(responseCode = "500", description = "Internal server error", content = @Content),
    })

Spring 启动 REST API 删除重复的响应主体

Spring boot REST API remove duplicated response body

rest

maven

swagger-ui

spring-boot

springdoc-openapi-ui