Spring Boot 中使用 Swagger2 构建 RESTful APIs

Spring Boot 中使用 Swagger2 构建 RESTful APIs Swagger 是一系列 RESTful API 的工具，通过 Swagger 可以获得项目的交互式文档，客户端 SDK 的自动生成等功能。Swagger 的目标是为 REST APIs 定义一个标准的、与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下，能发现和理解各种服务的功能。 Swagger 是世界上最流行的 API 表达工具。Swagger 是一个简单但功能强大的 API 表达工具。它具有地球上最大的 API 工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用 Swagger。使用 Swagger 生成 API，我们可以得到交互式文档，自动生成代码的 SDK 以及 API 的发现特性等。 使⽤用 Spring Boot 集成 Swagger 的理念是，使⽤用注解来标记出需要在 API 文档中展示的信息，Swagger 会根据项目中的标记的注解来生成对应的 API 文档。Swagger 被号称世界上最流行的 API 工具，它提供了 API 管理的全套解决方案，API 文档管理需要考虑的因素基本都包含。 在使用 Spring Boot 集成 Swagger 2.X 时，需要引入依赖并做基础配置。需要在 Maven 依赖中添加以下依赖项： <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency> 然后，需要创建一个 SwaggerConfig 配置类： @Configuration @EnableSwagger2 public class SwaggerConfig {} 在 SwaggerConfig 的类上添加两个注解：@Configuration，启动时加载此类；@EnableSwagger2，表示此项目启用 Swagger API 文档。 在 SwaggerConfig 中添加两个方法： @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 自行修改为自己的包路径 .apis(RequestHandlerSelectors.basePackage("com.neo.xxx")) .paths(PathSelectors.any()) .build(); } 此方法使用 @Bean，在启动时初始化，返回实例 Docket（Swagger API 摘要），这里需要注意的是.apis(RequestHandlerSelectors.basePackage("com.neo.xxx")) 指定需要扫描的包路径，只有此路径下的 Controller 类才会自动生成 Swagger API 文档。 private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("客户管理中心") .description("客户管理中心 API 1.0 操作文档") //服务条款网址 .termsOfServiceUrl("http://www.ityouknow.com/") .version("1.0") .contact(new Contact("纯洁的微笑", "http://www.ityouknow.com/", "")) .build(); } 在上面的代码中，我们使用 ApiInfoBuilder 来生成 API 的信息，包括标题、描述、服务条款网址、版本号等信息。 我们可以使用 Swagger 生成 API 文档，并在浏览器中访问 Swagger UI，以便更方便地测试和使用 API。 因此，使用 Spring Boot 集成 Swagger 2.X 可以方便地生成 RESTful APIs，并提供了一个交互式的 API 文档，提高了开发效率和API 的可读性。