Swagger的故事

隨著Web服務的發展，RESTful風格的API越來越受到開發者的青睞，因為它簡單且符合Web的本質。Spring框架也不落人后，提供了一個名為Spring MVC的模塊，用于支持RESTful API的開發。Spring MVC是一個基于注解的Web框架，讓開發者可以使用簡潔且優雅的方式定義和實現API。Lxs28資訊網——每日最新資訊28at.com

然而Spring MVC并沒有提供一個方便且標準的方式來描述和文檔化API，這給API的管理和維護帶來了一定的困難。為了解決這個問題，一個名為Swagger的項目誕生了。Swagger是由Tony Tam在2010年創建的一個開源項目，旨在為RESTful API提供一個規范且完整的框架4。Tony Tam是一個資深的Java開發者，他在使用Spring MVC開發API時感受到了它的優點和缺點，所以他決定創建一個可以與Spring MVC無縫集成的工具，來幫助開發者更好地設計、描述、調用和可視化API。Lxs28資訊網——每日最新資訊28at.com

Swagger項目很快就得到了開源社區和業界的認可和支持，成為了最流行的API開發工具之一。Swagger項目也不斷地演進和完善，涵蓋了各種語言和框架，如Python, Ruby, Node.js, Django, Rails等。Swagger項目也不斷地與其他標準和工具集成，如OpenAPI Specification, Postman, Apigee等。Lxs28資訊網——每日最新資訊28at.com

Swagger的作用

Swagger的主要作用是為RESTful風格的Web服務提供一個標準且完整的框架，包括以下幾個方面：Lxs28資訊網——每日最新資訊28at.com

• 生成：Swagger可以根據代碼或者手動編寫的規范文件，自動生成API文檔，包括請求參數、響應結果、錯誤碼等信息。這樣可以節省編寫文檔的時間，也可以保證文檔和代碼的一致性。
• 描述：Swagger可以使用一種結構化的語言（如YAML或JSON）來描述API的元數據，如接口名稱、路徑、方法、參數類型、返回值類型等。這樣可以方便地對API進行管理和維護，也可以方便地進行版本控制和協作開發。
• 調用：Swagger可以提供一個可視化的用戶界面（如Swagger UI），讓用戶可以直接在瀏覽器中對API進行測試和調試，而不需要使用其他的工具（如Postman或curl）。這樣可以提高開發效率，也可以方便地驗證API的功能和性能。
• 可視化：Swagger可以提供一個圖形化的用戶界面（如Swagger Editor），讓用戶可以以圖形化的方式編輯和查看API規范文件，而不需要關心語法細節。這樣可以提高用戶體驗，也可以方便地進行錯誤檢查和修正。

Swagger的好處

Swagger作為一個流行且成熟的API開發工具，它有以下幾個好處：Lxs28資訊網——每日最新資訊28at.com

• 標準化：Swagger遵循OpenAPI規范，這是一個業界公認且廣泛使用的RESTful API描述標準。使用Swagger可以保證API的兼容性和互操作性，也可以方便地與其他遵循OpenAPI規范的工具集成。
• 靈活性：Swagger支持多種編程語言和框架，如Java, Python, Ruby, Node.js, Spring, Django, Rails等。使用Swagger可以根據不同的需求和場景選擇合適的技術棧，也可以輕松地遷移和重構代碼。
• 易用性：Swagger提供了豐富且易用的工具和用戶界面，讓用戶可以快速地創建、修改、查看和測試API。使用Swagger可以降低API開發的門檻和難度，也可以提高API開發的質量和效率。

Swagger項目現在已經成為了一個龐大且活躍的生態系統，包括以下幾個部分：Lxs28資訊網——每日最新資訊28at.com

• Swagger Core：提供了一系列的庫和工具，用于生成、解析、驗證和轉換Swagger規范文件。
• Swagger UI：提供了一個可視化的用戶界面，用于展示、測試和調試API。
• Swagger Editor：提供了一個圖形化的用戶界面，用于編輯和查看Swagger規范文件。
• Swagger Codegen：提供了一個代碼生成器，用于根據Swagger規范文件生成客戶端和服務端代碼。
• Swagger Inspector：提供了一個在線工具，用于檢查、測試和分析API。
• Swagger Hub：提供了一個在線平臺，用于協作、管理和發布API。

Springboot使用Swagger3生成API文檔

步驟說明Lxs28資訊網——每日最新資訊28at.com

• 在pom.xml文件中添加springdoc-openapi-ui依賴，這是一個支持OAS 3.0的Swagger UI庫，它可以自動集成到Spring Boot應用中，并提供一個可視化的用戶界面來展示、測試和調試API。
• 在配置類中添加@OpenAPIDefinition注解，并定義一些API的基本信息，如標題、描述、版本、聯系人等。
• 在控制器類中添加@Tag注解，并定義一些API的分組信息，如名稱、描述等。
• 在方法上添加@Operation注解，并定義一些API的操作信息，如摘要、描述、響應等。
• 在參數上添加@Parameter注解，并定義一些API的參數信息，如名稱、描述、是否必填、示例等。
• 在模型類上添加@Schema注解，并定義一些API的模型信息，如名稱、描述、屬性等。

注意：Lxs28資訊網——每日最新資訊28at.com

對于2.x.x版本，訪問地址為：http://localhost:8080/{context-path}/swagger-ui.htmlLxs28資訊網——每日最新資訊28at.com

對于3.x.x版本，訪問地址為：http://localhost:8080/{context-path}/swagger-ui/index.htmlLxs28資訊網——每日最新資訊28at.com

其中，localhost是你的本地主機名，8080是你的項目端口號，{context-path}是你的項目上下文路徑。你需要根據你的實際情況來替換這些參數。Lxs28資訊網——每日最新資訊28at.com

例如，如果你的項目端口號是8081，上下文路徑是demo，Swagger版本是3.0.0，那么你可以訪問以下地址來查看Swagger UI界面：Lxs28資訊網——每日最新資訊28at.com

http://localhost:8081/demo/swagger-ui/index.htmlLxs28資訊網——每日最新資訊28at.com

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方法}

Lxs28資訊網——每日最新資訊28at.com

Swagger注解總結：

Swagger注解有以下幾種類型：Lxs28資訊網——每日最新資訊28at.com

• 類級別的注解：用于標識一個類是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常用注解的總結表格：Lxs28資訊網——每日最新資訊28at.com

Lxs28資訊網——每日最新資訊28at.com

本文鏈接：http://m.www897cc.com/showinfo-26-10899-0.html前后端分離項目必備——自動生成API文檔神器Swagger

聲明：本網頁內容旨在傳播知識，若有侵權等問題請及時與本網聯系，我們將在第一時間刪除處理。郵件：2376512515@qq.com

上一篇： 深入淺出：分布式、CAP 和 BASE 理論

下一篇： JavaScript 終于原生支持數組分組了！