springdoc-openapi：如何添加 POST 请求的示例？答案

【问题标题】：springdoc-openapi: How to add example of POST request?springdoc-openapi：如何添加 POST 请求的示例？
【发布时间】：2020-08-18 09:30:32
【问题描述】：

有如下Controller方法：

    @ApiResponses(value = {@ApiResponse(responseCode = "200")})
    @GetMapping(value = API_URI_PREFIX + PRODUCTS_URI, produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseStatus(HttpStatus.OK)
    public Flux<Product> getProducts(@Valid @NotNull PagingAndSorting pagingAndSorting) {
   }

我需要找到一种方法如何在Swagger 示例中显示PagingAndSorting 对象。

我正在使用springdoc-api v1.4.3。

【问题讨论】：

标签： java swagger swagger-ui springdoc springdoc-openapi-ui

【解决方案1】：

您可以使用@ExampleObject 注解。

请注意，如果您想引用示例现有对象，您也可以在示例中使用 ref @ExampleObject(ref="...")。或者理想情况下，从外部配置文件中获取示例并使用 OpenApiCustomiser 添加它们，就像在此测试中所做的那样：

https://github.com/springdoc/springdoc-openapi/blob/master/springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app90/SpringDocTestApp.java

这是使用@ExampleObject 的示例代码：

@PostMapping("/test/{id}")
public void testme(@PathVariable("id") String id, @RequestBody(content = @Content(examples = {
        @ExampleObject(
                name = "Person sample",
                summary = "person example",
                value =
                        "{\"email\": test@gmail.Com,"
                                + "\"firstName\": \"josh\","
                                + "\"lastName\": \"spring...\""
                                + "}")
})) PersonDTO personDTO) { }

如果您在控制器中使用 @RequestBody Spring 注释，则需要区分两者，例如使用 @io.swagger.v3.oas.annotations.parameters.RequestBody 作为 Swagger 注释。这可以防止下面的 cmets 中提到的空参数问题。

【讨论】：

@RequestBody(content = ....) 中的“内容”是什么？不编译。
好的。我尝试使用 import io.swagger.v3.oas.annotations.parameters.RequestBody;现在它编译了，但 RequestBody 参数不起作用。参数值（变量）= null。
@brianbro - 你有关于如何获取外部配置文件作为 ExampleObject 值的示例吗？试过这个但不工作： test(@Valid @RequestBody(content = @Content(examples = {@ExampleObject(name = "Example Body", summary = "Example Body", ref = "exampleFile.json") where exampleFile.json在我的 src/main/resource 文件夹中
如果我使用这个 - @io.swagger.v3.oas.annotations.parameters.RequestBody(content = @Content(examples = { @ExampleObject( name = "Person sample", summary = "person示例”，值 = “{“电子邮件”：test@gmail.Com，“+”“firstName”：“josh”，+“”lastName”：“spring...””+“}”）}））我得到以下异常-输入'，@io.swagger.v3.oas.annotations.parameters.RequestBody(content=@Content(examples={@ExampleObject(name="Person sample",summary="person example ",value="{\"email\": test@gmail.Com,"+"\"firstName\": \"josh\","+"\"lastName\": \"spring...\" "+"}")})))': NoViableAltException
有没有办法将资源文件内容添加到@ExampleObject？我正在尝试使用ref 从resources file 添加@ExampleObject，但由于某种原因它无法正常工作。我已经发布了我的问题：stackoverflow.com/q/71616547/7584240

【解决方案2】：

如果我们使用spring boot，要将其添加到我们的Maven项目中，我们需要在pom.xml文件中添加一个依赖项。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

@Configuration
@EnableSwagger2
public class SpringConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

没有 Spring Boot 的配置

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
      .addResourceLocations("classpath:/META-INF/resources/");
 
    registry.addResourceHandler("/webjars/**")
      .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

验证： 要验证 Springfox 是否正常工作，您可以在浏览器中访问以下 URL： http://localhost:8080/our-app-root/api/v2/api-docs

要使用 Swagger UI，需要一个额外的 Maven 依赖项：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

您可以在浏览器中访问 http://localhost:8080/our-app-root/swagger-ui.html 进行测试

【讨论】：