Swagger的故事

隨著Web服務(wù)的發(fā)展，RESTful風(fēng)格的API越來(lái)越受到開(kāi)發(fā)者的青睞，因?yàn)樗?jiǎn)單且符合Web的本質(zhì)。Spring框架也不落人后，提供了一個(gè)名為Spring MVC的模塊，用于支持RESTful API的開(kāi)發(fā)。Spring MVC是一個(gè)基于注解的Web框架，讓開(kāi)發(fā)者可以使用簡(jiǎn)潔且優(yōu)雅的方式定義和實(shí)現(xiàn)API。

然而Spring MVC并沒(méi)有提供一個(gè)方便且標(biāo)準(zhǔn)的方式來(lái)描述和文檔化API，這給API的管理和維護(hù)帶來(lái)了一定的困難。為了解決這個(gè)問(wèn)題，一個(gè)名為Swagger的項(xiàng)目誕生了。Swagger是由Tony Tam在2010年創(chuàng)建的一個(gè)開(kāi)源項(xiàng)目，旨在為RESTful API提供一個(gè)規(guī)范且完整的框架4。Tony Tam是一個(gè)資深的Java開(kāi)發(fā)者，他在使用Spring MVC開(kāi)發(fā)API時(shí)感受到了它的優(yōu)點(diǎn)和缺點(diǎn)，所以他決定創(chuàng)建一個(gè)可以與Spring MVC無(wú)縫集成的工具，來(lái)幫助開(kāi)發(fā)者更好地設(shè)計(jì)、描述、調(diào)用和可視化API。

Swagger項(xiàng)目很快就得到了開(kāi)源社區(qū)和業(yè)界的認(rèn)可和支持，成為了最流行的API開(kāi)發(fā)工具之一。Swagger項(xiàng)目也不斷地演進(jìn)和完善，涵蓋了各種語(yǔ)言和框架，如Python, Ruby, Node.js, Django, Rails等。Swagger項(xiàng)目也不斷地與其他標(biāo)準(zhǔn)和工具集成，如OpenAPI Specification, Postman, Apigee等。

Swagger的作用

Swagger的主要作用是為RESTful風(fēng)格的Web服務(wù)提供一個(gè)標(biāo)準(zhǔn)且完整的框架，包括以下幾個(gè)方面：

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

Swagger的好處

Swagger作為一個(gè)流行且成熟的API開(kāi)發(fā)工具，它有以下幾個(gè)好處：

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

Swagger項(xiàng)目現(xiàn)在已經(jīng)成為了一個(gè)龐大且活躍的生態(tài)系統(tǒng)，包括以下幾個(gè)部分：

• Swagger Core：提供了一系列的庫(kù)和工具，用于生成、解析、驗(yàn)證和轉(zhuǎn)換Swagger規(guī)范文件。
• Swagger UI：提供了一個(gè)可視化的用戶界面，用于展示、測(cè)試和調(diào)試API。
• Swagger Editor：提供了一個(gè)圖形化的用戶界面，用于編輯和查看Swagger規(guī)范文件。
• Swagger Codegen：提供了一個(gè)代碼生成器，用于根據(jù)Swagger規(guī)范文件生成客戶端和服務(wù)端代碼。
• Swagger Inspector：提供了一個(gè)在線工具，用于檢查、測(cè)試和分析API。
• Swagger Hub：提供了一個(gè)在線平臺(tái)，用于協(xié)作、管理和發(fā)布API。

Springboot使用Swagger3生成API文檔

步驟說(shuō)明

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

注意：

對(duì)于2.x.x版本，訪問(wèn)地址為：http://localhost:8080/{context-path}/swagger-ui.html

對(duì)于3.x.x版本，訪問(wèn)地址為：http://localhost:8080/{context-path}/swagger-ui/index.html

其中，localhost是你的本地主機(jī)名，8080是你的項(xiàng)目端口號(hào)，{context-path}是你的項(xiàng)目上下文路徑。你需要根據(jù)你的實(shí)際情況來(lái)替換這些參數(shù)。

例如，如果你的項(xiàng)目端口號(hào)是8081，上下文路徑是demo，Swagger版本是3.0.0，那么你可以訪問(wèn)以下地址來(lái)查看Swagger UI界面：

http://localhost:8081/demo/swagger-ui/index.html

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 = "這是一個(gè)使用Swagger3來(lái)開(kāi)發(fā)Spring Boot應(yīng)用中的API的示例",
                version = "1.0",
                contact = @Contact(
                        name = "張三",
                        email = "zhangsan@example.com",
                        url = "1"
                )
        )
)
public class SwaggerConfig {
}

控制器類

// 控制器類
@RestController
@RequestMapping("/user")
@Tag(name = "用戶管理API", description = "提供用戶相關(guān)的操作")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "根據(jù)ID查詢用戶信息", description = "返回用戶實(shí)體對(duì)象")
    @ApiResponse(responseCode = "200", description = "查詢成功")
    @ApiResponse(responseCode = "404", description = "用戶不存在")
    public User getUserById(@PathVariable("id") @Parameter(description = "用戶ID", required = true, example = "1") Long id) {
        // 模擬查詢數(shù)據(jù)庫(kù)
        User user = new User();
        user.setId(id);
        user.setName("張三");
        user.setAge(18);
        return user;
    }

    @PostMapping("/")
    @Operation(summary = "添加用戶信息", description = "返回添加結(jié)果")
    @ApiResponse(responseCode = "200", description = "添加成功")
    @ApiResponse(responseCode = "400", description = "參數(shù)錯(cuò)誤")
    public String addUser(@RequestBody @Parameter(description = "用戶實(shí)體對(duì)象", required = true) User user) {
        // 模擬插入數(shù)據(jù)庫(kù)
        return "添加成功";
    }

}

用戶實(shí)體類

// 用戶實(shí)體類
@Schema(name = "用戶實(shí)體類", description = "用戶的基本信息")
public class User {

    @Schema(description = "用戶ID")
    private Long id;

    @Schema(description = "用戶姓名")
    private String name;

    @Schema(description = "用戶年齡")
    private Integer age;

    // 省略getter和setter方法
}

Swagger注解總結(jié)：

Swagger注解有以下幾種類型：

• 類級(jí)別的注解：用于標(biāo)識(shí)一個(gè)類是Swagger的資源，可以設(shè)置一些全局的屬性，如tags、value等。常用的類級(jí)別的注解有@Api。
• 方法級(jí)別的注解：用于標(biāo)識(shí)一個(gè)方法是一個(gè)http請(qǐng)求的操作，可以設(shè)置一些操作相關(guān)的屬性，如value、notes、response等。常用的方法級(jí)別的注解有@ApiOperation、@ApiResponses、@ApiResponse等。
• 參數(shù)級(jí)別的注解：用于標(biāo)識(shí)一個(gè)方法的參數(shù)或者一個(gè)字段是API的參數(shù)，可以設(shè)置一些參數(shù)相關(guān)的屬性，如value、required、example等。常用的參數(shù)級(jí)別的注解有@ApiParam、@ApiImplicitParam等。
• 模型級(jí)別的注解：用于標(biāo)識(shí)一個(gè)類是API的模型，可以設(shè)置一些模型相關(guān)的屬性，如value、description等。常用的模型級(jí)別的注解有@ApiModel、@ApiModelProperty等。
• 忽略級(jí)別的注解：用于標(biāo)識(shí)一個(gè)類或者方法被忽略，不顯示在Swagger文檔上。常用的忽略級(jí)別的注解有@ApiIgnore。

下面是一個(gè)對(duì)Swagger常用注解的總結(jié)表格：