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开发环境中不可或缺的工具。