一、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面試】第一時間閱讀，回復【資料】獲取福利，回復【項目】獲取項目源碼，回復【簡歷模板】獲取簡歷模板，回復【學習路線圖】獲取學習路線圖。
)
