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 本地运行步骤

1. 下载源码或 clone 仓库：

git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui

2. 打开 dist/index.html 文件即可本地查看界面；

3. 替换默认的 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 使用（可本地部署）

1. 下载地址：https://github.com/swagger-api/swagger-editor

2. 运行方式：

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面试】第一时间阅读，回复【资料】获取福利，回复【项目】获取项目源码，回复【简历模板】获取简历模板，回复【学习路线图】获取学习路线图。