Swagger 安装使用教程
一、Swagger 简介
Swagger 是一套开放源代码的 API 文档生成工具链，现归属于 OpenAPI 规范。它支持 RESTful API 的定义、生成、测试和文档自动化。常见的使用工具包括 Swagger UI、Swagger Editor、Swagger Codegen 以及 SpringFox（Spring 集成库）。
二、常用组件说明
| 组件 | 作用 |
|---|---|
| Swagger UI | 可视化展示 API 接口文档 |
| Swagger Editor | 在线或本地编辑 OpenAPI 规范文件 |
| Swagger Codegen | 从 OpenAPI 规范生成代码 |
| SpringFox | 集成 Swagger 到 Spring Boot 项目 |
三、Swagger UI 安装与使用
3.1 下载方式
- GitHub 地址：https://github.com/swagger-api/swagger-ui
3.2 本地运行步骤
- 下载源码或 clone 仓库：
git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui
-
打开
dist/index.html文件即可本地查看界面； -
替换默认的
petstore接口为你自己的 API 文档地址：
const ui = SwaggerUIBundle({url: "http://localhost:8080/v2/api-docs", // 修改为你的文档地址...
});
四、Spring Boot 项目集成 Swagger（使用 SpringFox）
4.1 添加 Maven 依赖
<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>
4.2 创建 Swagger 配置类
@Configuration
@EnableOpenApi
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.OAS_30).select().apis(RequestHandlerSelectors.basePackage("com.example.controller")).paths(PathSelectors.any()).build();}
}
4.3 访问地址
项目启动后访问：
http://localhost:8080/swagger-ui/index.html
五、Swagger Editor 使用（可本地部署）
-
下载地址：https://github.com/swagger-api/swagger-editor
-
运行方式：
docker pull swaggerapi/swagger-editor
docker run -d -p 8888:8080 swaggerapi/swagger-editor
访问：http://localhost:8888
六、Swagger Codegen 使用
6.1 安装方式（JAR 包）
- 下载地址：https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/
6.2 生成代码命令示例
java -jar swagger-codegen-cli.jar generate \-i http://localhost:8080/v2/api-docs \-l java \-o ./generated-client
七、常见问题
Q1: Spring Boot 3.x 无法使用 SpringFox？
SpringFox 与 Spring Boot 3 不兼容，建议使用 Springdoc OpenAPI 代替。
Q2: 接口文档页面空白？
请检查 @RestController、@RequestMapping 注解是否正确，或接口是否被扫描。
八、学习资源推荐
- Swagger 官方文档
- OpenAPI 规范
- Springdoc OpenAPI
- B 站搜索“小奇Java面试”获取视频讲解
本文由“小奇Java面试”原创发布，转载请注明出处。
可以搜索【小奇JAVA面试】第一时间阅读，回复【资料】获取福利，回复【项目】获取项目源码，回复【简历模板】获取简历模板，回复【学习路线图】获取学习路线图。
