Swagger 3.0.0 - 看不到 @RequestBody 的架构答案

【问题标题】：Swagger 3.0.0 - doesn't see schema for @RequestBodySwagger 3.0.0 - 看不到 @RequestBody 的架构
【发布时间】：2021-03-16 08:07:29
【问题描述】：

我有使用 kotlin ('1.3.50') 编写的 springboot(2.11.RELEASE) webflux 应用程序。我想添加招摇文档。我添加到我的 build.gradle：

compile group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'

我的 Rest 控制器如下所示：

@RestController
@RequestMapping("/path", produces = [MediaType.APPLICATION_JSON_VALUE])
@Validated
class CreditApplicationController @Autowired constructor(
    private val creditService: CreditService
) {
    @PostMapping(consumes = [MediaType.APPLICATION_JSON_VALUE], produces = [MediaType.APPLICATION_JSON_VALUE])
    fun applyCredit(
        @Valid @RequestBody request: ApplyCreditRequest,
        @OperationId operationId: String
    ): Mono<ResponseEntity<ApplicationCreditResponse>> {
       ...

ApplyCreditRequest 是一个简单的 kotlin 数据类

    @Validated
    data class ApplyCreditRequest(
        @get:JsonProperty("application_id", required = true)
        @NotBlank(message = "application_id cannot be empty")
        val applicationId: String,
    
        @get:JsonProperty("customer_info", required = true)
        @field:Valid
        val customerInfo: CustomerInfo,
    
        @get:JsonProperty("credit_details", required = true)
        @field:Valid
        val creditDetails: CreditDetails,
    
        @get:JsonProperty("agent", required = true)
        @Valid
        val agent: Agent
)

但是，当我转到 swagger 生成的页面时，请求正文显示为字符串。如何让它显示为 ApplyCreditRequest json 我希望它是？

更新：

更新到：

@PostMapping(consumes = [MediaType.APPLICATION_JSON_VALUE], produces = [MediaType.APPLICATION_JSON_VALUE])
     fun applyCredit(
            @io.swagger.v3.oas.annotations.parameters.RequestBody(
                content = [
                    Content(
                        schema = Schema(
                            implementation = ApplyCreditRequest::class
                        )
                    )
                ]
            ) @Valid @RequestBody request: ApplyCreditRequest,
            @OperationId operationId: String
        ): Mono<ResponseEntity<ApplicationCreditResponse>> {

还是不行

【问题讨论】：

尝试使用@RequestBody(content = @Content(schema = @Schema(implementation = ApplyCreditRequest.class)))
@DebarghaRoy 仍然不起作用；c
抱歉，错过了您使用 Springfox 的事实。我上面分享的内容适用于 Springdoc。
您的问题解决了吗？
很遗憾，不，我必须创建自己的 swagger.yml 并托管它 - songrgg.github.io/operation/…

标签： spring-boot swagger swagger-ui swagger-2.0 springfox

【解决方案1】：

一般情况下，您可以将@ApiModel 注解添加到您将在请求中传递的对象。

（您还可以使用@ApiModelProperty 注释来注释对象的属性。）

Java 中的示例如下所示：

// TopicContoller.java
// The POST operation accepts a 'Topic' object in the request body, and returns the same object

@RestController
public class TopicContoller {

// Other detail omitted...

    @ApiOperation(
            value = "Add a topic",
            notes = "Adds a new topic.",
            response = Topic.class)
    
    @RequestMapping(method = RequestMethod.POST,value = "/topics")
    public Topic addTopic(@RequestBody Topic topic) {
        topicService.addTopic(topic);
        return topic;
    }

}

// Topic.java 
// The 'Topic' object

@ApiModel(description = "An object that represents a given topic.")
public class Topic {
    
    @ApiModelProperty(notes = "The Topic ID, as a unique String", example = "php")
    private String id;

    public String getId() {
        return id;
    }
    public void setId(String id) {
        this.id = id;
    }

// Other detail omitted...

}

【讨论】：

【解决方案2】：

我的一些请求使用@RequestBody 架构时遇到了类似的问题，而有些则没有，最终我在 swagger 文档中找到了以下内容

与 OpenAPI 2.0 的区别

如果您之前使用过 OpenAPI 2.0，这里是帮助您的更改摘要您开始使用 OpenAPI 3.0：

GET、DELETE 和 HEAD 不再允许具有请求正文，因为它没有按照 RFC 7231 定义的语义。

似乎基本的@RequestMapping 默认为获取请求。

在我的例子中，将映射更改为显式的@PostMapping 让我大摇大摆地看到请求正文中的架构。

...但这改变了 REST API 的语义，对我来说这是两害相权取其轻。

【讨论】：