Swagger UI实战指南：涵盖API开发周期的保姆级教程

Swagger 是一个强大的 API 开发工具，支持从设计到生产的整个API生命周期。它以 Swagger 规范格式（现在称为 OpenAPI 规范）为基础，提供了一套开源软件工具来帮助开发人员设计、构建、文档化以及使用 RESTful Web服务。

1、Swagger 的简介：

• Swagger定义：Swagger是一个用于设计、构建、记录和使用RESTful Web服务的接口文档规范和框架。
• Swagger作用：在前后端分离的开发模式中，后端提供接口服务，需要维护与接口匹配的文档。Swagger UI 则提供Web界面，用于展示和测试定义的RESTful接口，自动化生成接口文档，保持文档与代码的同步更新。

官网地址是：API Documentation & Design Tools for Teams | Swagger

官网界面如下：

2、使用Swagger的好处：

• 标准化文档：自动生成的 API 文档总是同步的，减少了维护不一致的风险。
• 开发效率：通过自动代码生成，可以快速构建前后端的连接。
• 交互式API探索：Swagger UI 支持开发者和最终用户直接与API交互，增加透明度和易用性。
• 跨语言支持：支持多种编程语言和框架，使得团队可以选择适合的技术栈。

3、Swagger与SpringBoot集成：

• 定义API：使用Swagger Editor编写并验证OpenAPI规范文件。这是开始Swagger集成的第一步，需确保API设计符合OpenAPI的规范。
• 引入依赖：在Spring Boot项目的pom.xml文件中加入springfox-swagger3和springfox-swagger-ui依赖。这一步确保了项目中包含了Swagger的核心功能和界面支持。
• 配置Swagger：创建一个Swagger配置类，使用@EnableSwagger3注解来启用Swagger。在这个配置类中，配置Docket Bean以定制Swagger的设置和API的信息。
• 控制器注解：在控制器类和方法上使用@Api和@ApiOperation注解来定义接口和详细操作。这有助于Swagger UI生成清晰、易懂的API文档。
• 生成和部署：使用Swagger Codegen根据OpenAPI规范生成服务器和客户端代码。然后部署这些API到你的服务器上，确保它们可以被访问和使用。
• 可视化和交互：部署Swagger UI，这样用户就可以通过一个友好的界面直观地看到API的功能并与之交互。Swagger UI也支持直接从浏览器对API进行测试。

4、Swagger UI的访问、API端点的调试：

1、熟悉界面：

•  打开Swagger UI界面：在浏览器中访问http://localhost:8080/swagger-ui.html (根据实际项目调整IP、端口号)，浏览API列表。Swagger UI会列出所有API端点，并根据controller分组。
• 选择具体的API端点：在API列表中，可以通过点击某个端点旁边的下拉箭头，展开查看该API的详细信息。
• 查看详细信息：一旦端点被展开，你可以查看到该端点的具体操作，如GET、POST等，以及可能的参数和响应消息。

2、登录认证：

• 在Swagger UI中输入username和项目中的password，点击execute执行登录。
• 如果响应状态码为200，表示登录成功。复制响应体中的token。

3、授权列表：

• 点击Swagger界面Authorize按钮。粘贴token到弹窗value输入框，点击Authorize进行授权。
• 授权成功后，value输入框显示为密文，Authorize按钮变为Logout按钮。

4、使用API：

• 点击界面旁的下拉框Select a definition，选择需要操作的模块。
• 输入所需操作的响应体，点击execute执行。
• 状态码200和描述OK表示操作成功。

注意：在操作过程中不要刷新页面，以免token过期导致退出登录！

通过这种方式，Swagger UI不仅提供直观界面来测试和验证API，还支持安全的用户认证和授权。这有助于开发者在开发和测试阶段高效地管理、测试API，确保应用安全可用。

通过上述步骤，我们还可以有效地在Spring Boot项目中集成Swagger，以提高API的开发、测试和文档化的效率。Swagger 的使用不仅可以提高开发效率，还可以提高 API 的透明度和可交互性，是现代Web开发环境中不可或缺的工具。