在具有复杂对象的 GET 端点上使用 swagger 生成 Spring API 文档答案

【问题标题】：generating spring API docs using swagger over GET endpoints with complex objects在具有复杂对象的 GET 端点上使用 swagger 生成 Spring API 文档
【发布时间】：2020-06-19 15:07:30
【问题描述】：

我有一个 spring boot 应用程序，我正在使用 springfox swagger 来生成 API 文档。

我有一个带有复杂嵌套对象的搜索端点

@GetMapping("/search")
public Something search(SearchDTO input) {
}

public class SearchDTO {
    private SearchFilterDto filters;
    private Page page;
    private Sort sort;
}

public class SearchFilterDto {
    private String name;
}

... other DTOS; getters and setters are omitted, default constructor

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

应用运行后，生成的文档是这样的

关于我可以帮助 springfox 为我的复杂对象生成文档的任何想法吗？

【问题讨论】：

您不能将 DTO 传递给 GET 请求
你可以。该端点按预期在生产中工作:)
真的吗？以及如何调用端点？
curl --location --request GET '.../search?filters.firstName=x&filters.lastName=y&sort.direction=ASC&sort.field=username&page.offset=1&page.size=2'。如果我没记错的话，我认为这从 Spring Boot 2.2 开始有效。

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

【解决方案1】：

我找到了问题。

在我的 DTO 中，我有一些返回 Optional<Something> 的吸气剂。通过将.genericModelSubstitutes(Optional.class) 添加到我的招摇配置中，我设法获得了我正在寻找的配置。

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            .genericModelSubstitutes(Optional.class)  // added this line
            .securityContexts(Lists.newArrayList(securityContext()))
            .securitySchemes(Lists.newArrayList(apiKey()));
}

【讨论】：