在 Spring 5 而非 Spring Boot 中记录 API 的最佳方式

Question

我正在尝试为我的 Spring 5 项目中的所有 API 添加 swagger 文档。我无法找出最好的方法。我看到我们可以使用 springdoc openapi 但大多数文档和示例都说明了如何在 Spring Boot 项目中执行此操作。我想在 Spring 5 项目中使用它。另外用Spring Fox可以吗？这是更好的选择，你可以用示例链接指导我吗？

Answer 1

向非 Spring Boot Spring 5 项目添加 Swagger 文档一开始可能会感觉有点棘手，因为大多数示例都是针对 Spring Boot 的。让我们回顾一下这些选项，并使其易于遵循。

对于 Spring 5（非 Spring Boot）项目，您有两个主要选项：Springdoc OpenAPI 和 Springfox。让我们深入研究每个选项并完成运行它的步骤。

---

选项 1：Springdoc OpenAPI

推荐

Springdoc OpenAPI 是现代的、积极维护的，并且与较新的 Spring 和 OpenAPI 规范配合良好。尽管它主要针对 Spring Boot，但您也可以使其适用于标准 Spring MVC 项目。方法如下：

1. 添加依赖项：打开

   pom.xml

   （假设您使用的是 Maven）并添加这些依赖项以包括

   springdoc-openapi

   和

   spring-webmvc

   。

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-ui</artifactId>
       <version>1.8.0</version>
   </dependency>
   <dependency>
       <groupId>org.springframework</groupId>
       <artifactId>spring-webmvc</artifactId>
       <version>5.3.39</version>
   </dependency>
   

2. 设置配置类：由于我们没有使用 Spring Boot，因此我们需要一个自定义配置类来手动加载 OpenAPI 设置。添加一个名为

   OpenApiConfig

   的新 Java 类，并按如下方式配置它：

   import org.springdoc.core.GroupedOpenApi;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   
   @Configuration
   public class OpenApiConfig {
   
       @Bean
       public GroupedOpenApi publicApi() {
           return GroupedOpenApi.builder()
                   .group("public")
                   .pathsToMatch("/api/**")
                   .build();
       }
   }
   

此设置告诉 Springdoc 扫描

/api/**

路径下的所有端点，并将它们包含在生成的文档中。

3. 访问 Swagger UI：设置后，启动您的应用程序。然后，打开浏览器并转到

   http://localhost:8080/swagger-ui.html

   查看正在运行的 API 文档！

---

选项2：Springfox

另一种选择

Springfox 是生成 Swagger 文档的流行选择，但现在维护较少。它可以与 Spring 5 一起使用以实现基本的 Swagger 功能，但它缺少 OpenAPI 的一些新功能。

使用Springfox：

1. 添加依赖项：将这些依赖项添加到您的

   pom.xml

   。

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>3.0.0</version>
   </dependency>
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>3.0.0</version> <!-- the latest version was in 2020 -->
   </dependency>
   

2. 创建 Swagger 配置类：与 Springdoc 一样，创建一个

   SwaggerConfig

   类来指定 Springfox 应如何扫描您的 API。

   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   
   @Configuration
   public class SwaggerConfig {
   
       @Bean
       public Docket api() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .select()
                   .apis(RequestHandlerSelectors.any())
                   .paths(PathSelectors.any())
                   .build();
       }
   }
   

3. 访问 Swagger UI：启动您的应用程序，然后访问

   http://localhost:8080/swagger-ui/

   查看文档。

---

选择哪一个？

如果您想要现代 Spring 版本的最新功能和更流畅的支持，请使用 Springdoc OpenAPI。如果您可能需要支持 OpenAPI 3.0 或其他新规范，那么它特别好。
• 如果您只需要基本的 Swagger 支持并且不需要高级功能，请使用 Springfox
，因为它更简单但功能不太丰富。