SpringBoot结合Swagger自动生成api文档.docx

### Spring Boot 结合 Swagger 自动生成 API 文档详解 #### 一、使用 IntelliJ IDEA 搭建 Spring Boot 工程 在正式介绍如何利用 Spring Boot 和 Swagger 来自动生成 API 文档之前，首先需要了解如何使用 IntelliJ IDEA 快速搭建一个 Spring Boot 的基础工程。 **1. 安装 IntelliJ IDEA 并配置 Java 环境** 确保本地计算机已安装 Java 开发环境（JDK），并正确设置 JAVA_HOME 环境变量。接着，下载并安装 IntelliJ IDEA。推荐使用专业版，它包含了更多功能。 **2. 安装 Spring Assistant 插件** 打开 IntelliJ IDEA，在 File -> Settings -> Plugins 中搜索 "Spring Assistant" 并进行安装。或者在 IntelliJ IDEA 的启动界面中选择 "Configure" -> "Plugins"，再搜索 "Spring Assistant" 进行安装。安装完成后重启 IntelliJ IDEA。 **3. 创建 Spring Boot 项目** - 打开 IntelliJ IDEA，选择 "File" -> "New" -> "Project..."。 - 在项目类型列表中选择 "Spring Initializr"。 - 根据需求选择或更改项目设置，如项目名称、位置、构建工具等。 - 添加所需依赖，例如 Spring Web。 - 点击 "Next" 直至完成创建。 完成以上步骤后，你可以运行创建好的 Spring Boot 应用来验证其是否正常启动。通常情况下，会在控制台输出 "Application started on port 8080" 或类似的信息。 #### 二、集成 Swagger 实现 API 文档自动生成 **1. 添加 Swagger 依赖** 在项目的 `pom.xml` 文件中添加以下依赖： ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency> ``` **2. 配置 Swagger** 创建一个新的 Bean 类，用来配置 Swagger 相关的设置。示例代码如下： ```java @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) .paths(PathSelectors.any()) .build(); } } ``` 其中 `RequestHandlerSelectors.basePackage` 设置了 Swagger 扫描的控制器包路径，可以根据实际情况调整。 **3. 访问 Swagger UI** 启动 Spring Boot 项目后，通过访问 `http://localhost:端口号/swagger-ui.html` 来查看 Swagger UI 页面。如果设置了特定的上下文路径，还需要在 URL 后添加该路径。 例如，如果项目端口号为 17664，且设置了上下文路径 `/demo`，则访问地址为 `http://localhost:17664/demo/swagger-ui.html`。 此外，还可以通过访问 `http://localhost:端口号/上下文路径/v2/api-docs` 获取 JSON 格式的 API 文档。 #### 三、将 Swagger 文档导出为 YAML 文件 **1. 获取 JSON 格式文档** 使用上述方法获取 Swagger 生成的 JSON 格式的 API 文档。 **2. 使用 Swagger Editor 转换为 YAML** 访问 Swagger Editor 在线工具 (http://editor.swagger.io/)，将 JSON 格式的文档粘贴到左侧编辑器中。系统会自动检测到格式，并询问是否转换为 YAML。点击确认即可完成转换。 转换完成后，右侧将显示 YAML 格式的 API 文档。可以将左侧的内容复制并保存为 `.yaml` 文件，以便后续使用。 总结起来，通过上述步骤，我们可以轻松地利用 Spring Boot 和 Swagger 实现 API 接口文档的自动生成与管理，极大地提高了开发效率和文档维护的便捷性。