前后端分離項目必備——自動生成API文檔神器Swagger
Swagger的故事
隨著Web服務的發展，RESTful風格的API越來越受到開發者的青睞，因為它簡單且符合Web的本質。Spring框架也不落人后，提供了一個名為Spring MVC的模塊，用于支持RESTful API的開發。Spring MVC是一個基于注解的Web框架，讓開發者可以使用簡潔且優雅的方式定義和實現API。
然而Spring MVC并沒有提供一個方便且標準的方式來描述和文檔化API，這給API的管理和維護帶來了一定的困難。為了解決這個問題，一個名為Swagger的項目誕生了。Swagger是由Tony Tam在2010年創建的一個開源項目，旨在為RESTful API提供一個規范且完整的框架4。Tony Tam是一個資深的Java開發者，他在使用Spring MVC開發API時感受到了它的優點和缺點，所以他決定創建一個可以與Spring MVC無縫集成的工具，來幫助開發者更好地設計、描述、調用和可視化API。
Swagger項目很快就得到了開源社區和業界的認可和支持，成為了最流行的API開發工具之一。Swagger項目也不斷地演進和完善，涵蓋了各種語言和框架，如Python, Ruby, Node.js, Django, Rails等。Swagger項目也不斷地與其他標準和工具集成，如OpenAPI Specification, Postman, Apigee等。
Swagger的作用
Swagger的主要作用是為RESTful風格的Web服務提供一個標準且完整的框架，包括以下幾個方面：
- 生成：Swagger可以根據代碼或者手動編寫的規范文件，自動生成API文檔，包括請求參數、響應結果、錯誤碼等信息。這樣可以節省編寫文檔的時間，也可以保證文檔和代碼的一致性。
- 描述：Swagger可以使用一種結構化的語言（如YAML或JSON）來描述API的元數據，如接口名稱、路徑、方法、參數類型、返回值類型等。這樣可以方便地對API進行管理和維護，也可以方便地進行版本控制和協作開發。
- 調用：Swagger可以提供一個可視化的用戶界面（如Swagger UI），讓用戶可以直接在瀏覽器中對API進行測試和調試，而不需要使用其他的工具（如Postman或curl）。這樣可以提高開發效率，也可以方便地驗證API的功能和性能。
- 可視化：Swagger可以提供一個圖形化的用戶界面（如Swagger Editor），讓用戶可以以圖形化的方式編輯和查看API規范文件，而不需要關心語法細節。這樣可以提高用戶體驗，也可以方便地進行錯誤檢查和修正。
Swagger的好處
Swagger作為一個流行且成熟的API開發工具，它有以下幾個好處：
- 標準化：Swagger遵循OpenAPI規范，這是一個業界公認且廣泛使用的RESTful API描述標準。使用Swagger可以保證API的兼容性和互操作性，也可以方便地與其他遵循OpenAPI規范的工具集成。
- 靈活性：Swagger支持多種編程語言和框架，如Java, Python, Ruby, Node.js, Spring, Django, Rails等。使用Swagger可以根據不同的需求和場景選擇合適的技術棧，也可以輕松地遷移和重構代碼。
- 易用性：Swagger提供了豐富且易用的工具和用戶界面，讓用戶可以快速地創建、修改、查看和測試API。使用Swagger可以降低API開發的門檻和難度，也可以提高API開發的質量和效率。
Swagger項目現在已經成為了一個龐大且活躍的生態系統，包括以下幾個部分：
- Swagger Core：提供了一系列的庫和工具，用于生成、解析、驗證和轉換Swagger規范文件。
- Swagger UI：提供了一個可視化的用戶界面，用于展示、測試和調試API。
- Swagger Editor：提供了一個圖形化的用戶界面，用于編輯和查看Swagger規范文件。
- Swagger Codegen：提供了一個代碼生成器，用于根據Swagger規范文件生成客戶端和服務端代碼。
- Swagger Inspector：提供了一個在線工具，用于檢查、測試和分析API。
- Swagger Hub：提供了一個在線平臺，用于協作、管理和發布API。
Springboot使用Swagger3生成API文檔
步驟說明
- 在pom.xml文件中添加springdoc-openapi-ui依賴，這是一個支持OAS 3.0的Swagger UI庫，它可以自動集成到Spring Boot應用中，并提供一個可視化的用戶界面來展示、測試和調試API。
- 在配置類中添加@OpenAPIDefinition注解，并定義一些API的基本信息，如標題、描述、版本、聯系人等。
- 在控制器類中添加@Tag注解，并定義一些API的分組信息，如名稱、描述等。
- 在方法上添加@Operation注解，并定義一些API的操作信息，如摘要、描述、響應等。
- 在參數上添加@Parameter注解，并定義一些API的參數信息，如名稱、描述、是否必填、示例等。
- 在模型類上添加@Schema注解，并定義一些API的模型信息，如名稱、描述、屬性等。
注意：
對于2.x.x版本，訪問地址為：http://localhost:8080/{context-path}/swagger-ui.html
對于3.x.x版本，訪問地址為：http://localhost:8080/{context-path}/swagger-ui/index.html
其中，localhost是你的本地主機名，8080是你的項目端口號，{context-path}是你的項目上下文路徑。你需要根據你的實際情況來替換這些參數。
例如，如果你的項目端口號是8081，上下文路徑是demo，Swagger版本是3.0.0，那么你可以訪問以下地址來查看Swagger UI界面：
pom.xml文件
<dependencies>
<!-- Spring Boot Starter -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- springdoc-openapi-ui -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.12</version>
</dependency>
</dependencies>配置類
// 配置類
@Configuration
@OpenAPIDefinition(
info = @Info(
title = "Swagger3示例API",
description = "這是一個使用Swagger3來開發Spring Boot應用中的API的示例",
version = "1.0",
contact = @Contact(
name = "張三",
email = "zhangsan@example.com",
url = "1"
)
)
)
public class SwaggerConfig {
}控制器類
// 控制器類
@RestController
@RequestMapping("/user")
@Tag(name = "用戶管理API", description = "提供用戶相關的操作")
public class UserController {
@GetMapping("/{id}")
@Operation(summary = "根據ID查詢用戶信息", description = "返回用戶實體對象")
@ApiResponse(responseCode = "200", description = "查詢成功")
@ApiResponse(responseCode = "404", description = "用戶不存在")
public User getUserById(@PathVariable("id") @Parameter(description = "用戶ID", required = true, example = "1") Long id) {
// 模擬查詢數據庫
User user = new User();
user.setId(id);
user.setName("張三");
user.setAge(18);
return user;
}
@PostMapping("/")
@Operation(summary = "添加用戶信息", description = "返回添加結果")
@ApiResponse(responseCode = "200", description = "添加成功")
@ApiResponse(responseCode = "400", description = "參數錯誤")
public String addUser(@RequestBody @Parameter(description = "用戶實體對象", required = true) User user) {
// 模擬插入數據庫
return "添加成功";
}
}用戶實體類
// 用戶實體類
@Schema(name = "用戶實體類", description = "用戶的基本信息")
public class User {
@Schema(description = "用戶ID")
private Long id;
@Schema(description = "用戶姓名")
private String name;
@Schema(description = "用戶年齡")
private Integer age;
// 省略getter和setter方法
}
Swagger注解總結：
Swagger注解有以下幾種類型：
- 類級別的注解：用于標識一個類是Swagger的資源，可以設置一些全局的屬性，如tags、value等。常用的類級別的注解有@Api。
- 方法級別的注解：用于標識一個方法是一個http請求的操作，可以設置一些操作相關的屬性，如value、notes、response等。常用的方法級別的注解有@ApiOperation、@ApiResponses、@ApiResponse等。
- 參數級別的注解：用于標識一個方法的參數或者一個字段是API的參數，可以設置一些參數相關的屬性，如value、required、example等。常用的參數級別的注解有@ApiParam、@ApiImplicitParam等。
- 模型級別的注解：用于標識一個類是API的模型，可以設置一些模型相關的屬性，如value、description等。常用的模型級別的注解有@ApiModel、@ApiModelProperty等。
- 忽略級別的注解：用于標識一個類或者方法被忽略，不顯示在Swagger文檔上。常用的忽略級別的注解有@ApiIgnore。
下面是一個對Swagger常用注解的總結表格：
