寫(xiě)在前面

在現(xiàn)目前項(xiàng)目開(kāi)發(fā)中，一般都是前后端分離項(xiàng)目。前端小姐姐負(fù)責(zé)開(kāi)發(fā)前端，苦逼的我們負(fù)責(zé)后端開(kāi)發(fā)

事實(shí)是一個(gè)人全干，在這過(guò)程中編寫(xiě)接口文檔就顯得尤為重要了。然而作為一個(gè)程序員，最怕的莫過(guò)于自己寫(xiě)文檔和別人不寫(xiě)文檔

大家都不想寫(xiě)文檔，那這活就交給今天的主角Swagger來(lái)實(shí)現(xiàn)了

一、專(zhuān)業(yè)名詞介紹

①OpenApi是什么？

解答：OpenApi是一個(gè)用于描述、定義和共享 RESTful API 文檔的規(guī)范。最新規(guī)范是 OpenAPI 3.0

② Swagger是什么？

解答： Swagger 是一個(gè)用于設(shè)計(jì)和測(cè)試 RESTful APIs 的工具。

它提供了API 描述、請(qǐng)求和響應(yīng)示例、API 測(cè)試和文檔生成等豐富的功能。最新版本是Swagger3,支持OpenAPI3.0規(guī)范

③ SpringFox 是什么？

SpringFox 是 Spring 社區(qū)維護(hù)的一個(gè)項(xiàng)目（非官方），幫助使用者將 Swagger 2 集成到 Spring 中。

目前國(guó)內(nèi)項(xiàng)目使用的都是它

github地址：https://github.com/springfox/springfox

④springDoc是什么？

解答： Spring-doc也是 Spring 社區(qū)維護(hù)的一個(gè)項(xiàng)目（非官方），幫助使用者將 Swagger 3 集成到 Spring 中

SpringDoc 支持 Swagger 頁(yè)面 Oauth2 登錄，相較于 SpringFox 而言，它的支撐時(shí)間更長(zhǎng)，無(wú)疑是更好的選擇。

但是在國(guó)內(nèi)發(fā)展較慢，網(wǎng)上一找資料，出來(lái)的基本上是 Swagger2的內(nèi)容。

地址：https://springdoc.org/

⑤ OpenAPI 、Spring-doc和 Swagger 之間的關(guān)系

解答：OpenAPI 定義了一種標(biāo)準(zhǔn)的格式來(lái)表示 API 文檔，而 Swagger 是一個(gè)實(shí)現(xiàn) OpenAPI 規(guī)范的工具

二、Swagger詳細(xì)簡(jiǎn)介

Swagger 江湖人稱(chēng)“絲襪哥”，是一個(gè)幫助程序員生成接口文檔的利器。

只需要簡(jiǎn)單配置，就可以生成帶有漂亮UI界面的接口文檔，而且編寫(xiě)的接口代碼變了

接口文檔隨之也跟著變，做到了真正的解放雙手。

官網(wǎng)https://swagger.io/

Swagger 優(yōu)點(diǎn)

號(hào)稱(chēng)世界上最流行的API框架

• Restful Api 文檔在線(xiàn)自動(dòng)生成器
• 直接運(yùn)行，支持在線(xiàn)測(cè)試API
• 不僅僅支持Java，還支持多種語(yǔ)言（如：PHP、Python、Node.js等）

三、小試牛刀

說(shuō)了這么多Swagger 的優(yōu)點(diǎn)，接下來(lái)就小試牛刀，看看怎么將Swagger集成到SpringBoot中。

3.1、環(huán)境介紹

• JDK：17
• SpringBoot：3.3.0
• Springdoc

注： 細(xì)心的小伙伴可能已經(jīng)發(fā)現(xiàn)了，在springboot3.0之前我用的都是Springfox來(lái)集成Swagger管理我們的API接口文檔,

但是Springfox已經(jīng)停止更新了，我們使用的是SpringBoot3 +jdk17 的環(huán)境后，Spring官網(wǎng)推薦了Springdoc 來(lái)整合swagger

3.2 新建一個(gè)springboot-web項(xiàng)目

3.3 添加依賴(lài)

由于篇幅原因，其他web項(xiàng)目相關(guān)依賴(lài)這里就不一一貼出來(lái)了。

第一個(gè)依賴(lài)是必須的，而且版本必須大于2.0.0

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.2.0</version>
</dependency>

注：

我們這里使用的是jdk17+springboot3.3.0 環(huán)境，原來(lái)swagger的V2和V3都不能用了，小伙伴們一定更要注意這兒

如果引入上面錯(cuò)誤的依賴(lài)，項(xiàng)目啟動(dòng)會(huì)報(bào)下面錯(cuò)誤，這時(shí)候我們引入上面正確的依賴(lài)重新啟動(dòng)項(xiàng)目即可

3.4 編寫(xiě)HelloController

新建一個(gè)controller包--->建立一個(gè)HelloController類(lèi)

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

我們?cè)跒g覽器中輸入“http://localhost:8080/hello” 后回車(chē)，出現(xiàn)如下界面，說(shuō)明我們的hello開(kāi)發(fā)成功了

3.5 訪(fǎng)問(wèn)swagger接口頁(yè)面

注：我們這里采用的是openapi ,所以就不用像swagger的V2和v3那樣添加配置類(lèi)了

瀏覽器直接輸入：http://localhost:8080/swagger-ui/index.html 回車(chē)即可看到下面界面

整合swagger是不是很簡(jiǎn)單呢

四、修改接口

從上面截圖中我們看到，我們?cè)?code>HelloController 中只定義了一個(gè)接口，但是前端UI界面中出來(lái)個(gè)7種請(qǐng)求方式（GET、PUT、POST、DELETE、OPTIONS、HEAD、PATCH）的接口，這是為什么呢？

解答：@RequestMapping("/hello") 我們接口中只是指定了訪(fǎng)問(wèn)地址，并沒(méi)有指定請(qǐng)求方式

我們將注解修改成@RequestMapping(path = "/hello",method = RequestMethod.GET)

或者@GetMapping("/hello") 然后重啟服務(wù)，我們看到界面上就只有一種請(qǐng)求方式的接口了

五、接口文檔常用配置

5.1 配置訪(fǎng)問(wèn)路徑

在application.yml中可以自定義api-docs和swagger-ui的訪(fǎng)問(wèn)路徑。當(dāng)然了，如果沒(méi)配置，默認(rèn)就是下面路徑

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

5.2 配置接口文檔基本信息

① 配置接口基本信息

新建一個(gè)config包--->并在包下建立一個(gè)SpringDocConfig配置類(lèi)

② 配置接口文檔基礎(chǔ)信息

我們?cè)谂渲妙?lèi)中添加如下代碼，

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                // 配置接口文檔基本信息
                .info(this.getApiInfo())
                ;
    }
    private Info getApiInfo() {
        return new Info()
                 // 配置文檔標(biāo)題
                .title("SpringBoot3集成Swagger3")
                // 配置文檔描述
                .description("SpringBoot3集成Swagger3示例文檔")
                // 配置作者信息
                .contact(new Contact().name("程序員小凡").url("https://www.xiezhrspace.cn").email("1666397814@163.com"))
                // 配置License許可證信息
                .license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
                // 概述信息
                .summary("SpringBoot3集成Swagger3示例文檔aaa")
                .termsOfService("https://www.xiezhrspace.cn")
                // 配置版本號(hào)
                .version("2.0");
    }
}

前端頁(yè)面訪(fǎng)問(wèn)接口文檔頁(yè)面后顯示如下

② 配置接口servers信息

接口可能存在多環(huán)境，如開(kāi)發(fā)環(huán)境、測(cè)試環(huán)境、生產(chǎn)環(huán)境等

我們可以通過(guò)@OpenAPIDefinition 配合servers 屬性來(lái)配置不同環(huán)境，具體配置示例如下

@OpenAPIDefinition(
        servers = {
                @Server(description = "開(kāi)發(fā)環(huán)境服務(wù)器", url = "http://localhost:8080"),
                @Server(description = "測(cè)試環(huán)境服務(wù)器", url = "https://test.xiezhr.com")
        }
)
@Configuration
public class SpringDocConfig {
    //...
}

配置完成后，瀏覽器訪(fǎng)問(wèn)顯示如下

③ 配置外部文檔信息

有時(shí)候我們需要在在線(xiàn)接口文檔中可以顯示跳轉(zhuǎn)到API的一些外部文檔（比如 項(xiàng)目部署文檔等）

這個(gè)時(shí)候我們可以通過(guò)@OpenAPIDefinition 配合 externalDocs 屬性來(lái)配置外部文檔

具體配置如下

@OpenAPIDefinition(
    externalDocs = @ExternalDocumentation(
        description = "項(xiàng)目編譯部署說(shuō)明",
        url = "http://localhost:8080/deplay/readme.md"
    )
)
@Configuration
public class SpringDocConfig {
    //......
}

配置完后重啟服務(wù)，瀏覽器訪(fǎng)問(wèn)接口文檔，顯示如下

SpringDocConfig 類(lèi)完整配置代碼如下

@OpenAPIDefinition(
        servers = {
                @Server(description = "開(kāi)發(fā)環(huán)境服務(wù)器", url = "http://localhost:8080"),
                @Server(description = "測(cè)試環(huán)境服務(wù)器", url = "https://test.xiezhr.com")
        },
        externalDocs = @ExternalDocumentation(
                description = "項(xiàng)目編譯部署說(shuō)明",
                url = "http://localhost:8080/deplay/readme.md"
        )
)
@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                // 配置接口文檔基本信息
                .info(this.getApiInfo())
                ;
    }
    private Info getApiInfo() {
        return new Info()
                 // 配置文檔標(biāo)題
                .title("SpringBoot3集成Swagger3")
                // 配置文檔描述
                .description("SpringBoot3集成Swagger3示例文檔")
                // 配置作者信息
                .contact(new Contact().name("程序員小凡").url("https://www.xiezhrspace.cn").email("1666397814@163.com"))
                // 配置License許可證信息
                .license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
                //
                .summary("SpringBoot3集成Swagger3示例文檔aaa")
                .termsOfService("https://www.xiezhrspace.cn")
                // 配置版本號(hào)
                .version("2.0");
    }
}

配置完上面信息后，重啟服務(wù)，瀏覽器訪(fǎng)問(wèn)：http://localhost:8080/v3/swagger-ui/index.html

5.3 配置掃描接口

應(yīng)用場(chǎng)景：

有時(shí)候我們?yōu)榱藰I(yè)務(wù)需要，我們建立了多個(gè)包下的接口，如admin包下的，common包下的接口，

為了安全起見(jiàn)，我們只允許接口文檔中訪(fǎng)問(wèn)comm包下面的接口。

在不加任何配置的情況下，所以接口都會(huì)默認(rèn)顯示，具體如下

配置掃描接口包：

在application.yml中可以自定義要掃描的接口包

springdoc:
  packages-to-scan: com.xiezhr.swaggerdemo.common.controller

配置好之后重啟服務(wù)，我們發(fā)現(xiàn)前臺(tái)UI只顯示了common包下面的接口了

5.4 配置接口文檔開(kāi)關(guān)

使用場(chǎng)景：

為了接口安全，我們一般需要在測(cè)試（test）環(huán)境或者開(kāi)發(fā)(dev)環(huán)境中開(kāi)啟接口文檔，而在生產(chǎn)（prod）環(huán)境中 關(guān)閉接口文檔

這個(gè)應(yīng)該怎么做呢？

這里涉及到SpringBoot多環(huán)境配置，忘記的小伙伴可以翻一翻之前的文章。傳送門(mén)：

我們創(chuàng)建三個(gè)配置文件，分別為

• ① application-dev.yml 開(kāi)發(fā)環(huán)境
• ② application-test.yml 測(cè)試環(huán)境
• ③ application-prod.yml 生產(chǎn)環(huán)境

只需在①和②配置文件中添加如下配置

springdoc:
  api-docs:
    enabled: true

而③配置文件中添加

springdoc:
  api-docs:
    enabled: false

通過(guò)上面配置后，我們?cè)陂_(kāi)發(fā)和測(cè)試環(huán)境下：就能正常訪(fǎng)問(wèn)http://localhost:8080/v3/swagger-ui/index.html#/

而在生產(chǎn)環(huán)境下就無(wú)法訪(fǎng)問(wèn)，報(bào)如下錯(cuò)誤

5.5 配置API分組

為了演示API分組，我們?cè)?code>controller包下面再建立admin包和common包，包下分別添加AdminController和CommonController接口類(lèi),結(jié)構(gòu)及代碼如下

① AdminController類(lèi)

// AdminController
@RestController
@RequestMapping("/admin")
public class AdminController {
    @GetMapping("/index")
    public String  admin(){
        return "admin";
    }
}

② CommonController 類(lèi)

@RestController
@RequestMapping("/common")
public class CommonController {
   @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

在默認(rèn)情況（沒(méi)有分組）的情況下，所有包下接口都顯示在一一個(gè)默認(rèn)組下面，如/common/* 和/admin/* 訪(fǎng)問(wèn)路徑下的接口都顯示在一起，如下圖所示

這時(shí)，如果/common/* 下的接口比較多，/admin/* 下的接口也比較多，界面上顯示就很混亂

解決辦法就是添加分組信息，我們?cè)?code>SpringDocConfig 配置類(lèi)中添加如下代碼,這樣就把接口分為了"common通用模塊組" 和"admin模塊組" 兩個(gè)組

@Bean("commonGroupApi")
public GroupedOpenApi webGroupApi() {
    return GroupedOpenApi.builder().group("common通用模塊組")
        .pathsToMatch("/common/**")
        .build();
}
@Bean("adminGroupApi")
public GroupedOpenApi adminGroupApi() {
    return GroupedOpenApi.builder().group("admin模塊組")
        .pathsToMatch("/admin/**")
        .build();
}

重啟服務(wù)，再訪(fǎng)問(wèn)http://localhost:8080/v3/swagger-ui/index.html 如下

5.6 配置接口信息

① @Tag 注解使用

對(duì)一個(gè) operation 進(jìn)行說(shuō)明或定義的標(biāo)簽，用在類(lèi)或方法上，也可以用在 @OpenAPIDefinition 中定義標(biāo)簽。

常用參數(shù)：

• name: 名稱(chēng)
• description: 接口描述信息

示例：

用在類(lèi)上

@RestController
@RequestMapping("/common")
@Tag(name = "公共接口", description = "公共接口")
public class CommonController {
    //......
}

② @Operation 注解使用

用于說(shuō)明方法用途，用在方法上。

參數(shù)：

• summary：方法概要，方法的一個(gè)簡(jiǎn)單介紹，建議 120 個(gè)字符內(nèi)
• description：方法描述，一般是很長(zhǎng)的內(nèi)容
• hidden：是否隱藏

示例：

@GetMapping("/hello")
@Operation(summary = "hello接口", description = "hello接口描述" ,hidden = true)
public String hello(){
    return "hello";
}

③ @Parameter注解使用

用于說(shuō)明方法參數(shù)，用在方法參數(shù)上。

參數(shù)：

• name：指定的參數(shù)名
• in：參數(shù)位置，可選 query、header、path 或 cookie，默認(rèn)為空，表示忽略
• description：參數(shù)描述
• required：是否必填，默認(rèn)為 false

示例：

@GetMapping("/user/{id}")
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用戶(hù)ID",required = true) @PathVariable("id") Integer id){
    User user = userService.getUserById(id);
    return user;
}

前端頁(yè)面查看

④ @ApiResponse 注解使用

用于說(shuō)明一個(gè)響應(yīng)信息，用在 @ApiResponses 中。

參數(shù)：

• responseCode：HTTP 響應(yīng)碼
• description：描述

示例：

@GetMapping("/user/{id}")
@Operation(summary = "獲取用戶(hù)信息", description = "根據(jù)用戶(hù)ID獲取用戶(hù)信息")
@ApiResponses(value ={
    @ApiResponse(responseCode = "200", description = "請(qǐng)求成功"),
    @ApiResponse(responseCode = "404", description = "用戶(hù)不存在")            
})
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用戶(hù)ID",required = true) @PathVariable("id") Integer id){
    User user = userService.getUserById(id);
    return user;
}

完整配置

@RestController
@RequestMapping("/common")
@Tag(name = "公共接口", description = "公共接口")
public class CommonController {
    @Autowired
    private IUserService userService;
   @GetMapping("/hello")
   @Operation(summary = "hello接口", description = "hello接口描述" ,hidden = true)
    public String hello(){
        return "hello";
    }
    @GetMapping("/hi")
    @Operation(summary = "hi接口", description = "hi接口描述")
    public String Hi(){
        return "Hi 程序員小凡";
    }
    @GetMapping("/user/{id}")
    @Operation(summary = "獲取用戶(hù)信息", description = "根據(jù)用戶(hù)ID獲取用戶(hù)信息")
    @ApiResponses(value ={
            @ApiResponse(responseCode = "200", description = "請(qǐng)求成功"),
            @ApiResponse(responseCode = "404", description = "用戶(hù)不存在")
    })
    public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用戶(hù)ID",required = true) @PathVariable("id") Integer id){
        User user = userService.getUserById(id);
        return user;
    }
}

重啟后，瀏覽器訪(fǎng)問(wèn)http://localhost:8080/v3/swagger-ui/index.html 如下

5.7 配置實(shí)體信息

① 新建一個(gè)User實(shí)體類(lèi)

@Data
public class User {
    private String name;
    private Integer age;
    private String email;
    private String address;
}

② @Schema標(biāo)簽使用

用于描述數(shù)據(jù)對(duì)象信息或數(shù)據(jù)對(duì)象屬性，比如各種POJO類(lèi)及屬性，用在類(lèi)或類(lèi)屬性上。

參數(shù)：

• name：屬性名稱(chēng)
• description：屬性描述
• required：是否必須
• minLength：字符最小長(zhǎng)度
• maxLength：字符最大長(zhǎng)度

③使用示例：

@Data
@Schema(description = "用戶(hù)實(shí)體類(lèi)",name = "User")
public class User {
    @Schema(description = "用戶(hù)名",name =  "name",minLength =  6,maxLength = 20,required = true)
    private String name;
    @Schema(description = "年齡",name =  "age",required = true,minimum = "1",maximum = "100")
    private Integer age;
    @Schema(description = "郵箱",name =  "email",required = true)
    private String email;
    @Schema(description = "地址",name =  "address")
    private String address;
}

④ 瀏覽器訪(fǎng)問(wèn)：http://localhost:8080/v3/swagger-ui/index.html ，我們看到配置的實(shí)體信息顯示出來(lái)了

六、接口調(diào)試

通過(guò)上面各種配置之后，我們的在線(xiàn)接口文檔基本上生成得差不多了。接下來(lái)我們就來(lái)說(shuō)說(shuō)怎么使用在線(xiàn)接口文檔進(jìn)行接口測(cè)試

① 測(cè)試說(shuō)明

在之前小節(jié)中我們開(kāi)發(fā)了要給根據(jù)用戶(hù)ID 獲取用戶(hù)信息的接口getUser。我們現(xiàn)在要做的就是在前端UI界面中找到這個(gè)接口，

在開(kāi)發(fā)環(huán)境下輸入用戶(hù)ID值，然后獲取用戶(hù)信息。

② 選擇組信息

【獲取用戶(hù)信息】這個(gè)接口在，common通用模塊組下面，所以我們第一步就要前端UI界面右上角選擇這個(gè)組

② 選擇開(kāi)發(fā)環(huán)境

在Servers 下選擇配置好的開(kāi)發(fā)環(huán)境

③ 找到我們要測(cè)試的接口

④ 測(cè)試接口，獲取響應(yīng)數(shù)據(jù)

接口右邊下三角箭頭展開(kāi)接口------>點(diǎn)擊Try it out

輸入?yún)?shù)：用戶(hù)ID------> 點(diǎn)擊【Execute】----->在Response body 中查看接口響應(yīng)信息

七、添加請(qǐng)求頭

很多時(shí)候我們接口都需要認(rèn)證之后才能訪(fǎng)問(wèn)，這時(shí)候我們就需要接口調(diào)用的時(shí)候攜帶著Token信息

示例：

我們通過(guò)@RequestHeader 注解 獲取請(qǐng)求頭中token信息

@GetMapping("/index")
public String  admin(@RequestHeader ("token") String token){
	System.out.println("token>>>>>>>>>>>>>>>>>>>>>>>>"+token);
    //token 驗(yàn)證
    //.....各種業(yè)務(wù)邏輯
    return "admin";
}

本文來(lái)自博客園，作者：xiezhr，轉(zhuǎn)載請(qǐng)注明原文鏈接：https://www.cnblogs.com/xiezhr/p/18253311

到此這篇關(guān)于SpringBoot3整合SpringDoc實(shí)現(xiàn)在線(xiàn)接口文檔的文章就介紹到這了,更多相關(guān)SpringBoot3在線(xiàn)接口文檔內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論