Swagger

隨著前后端分離架構和微服務架構的流行，我們使用Spring Boot來構建RESTful API項目的場景越來越多，在多人協(xié)作的團隊中，前后端的溝通成本往往比較大。在這樣的背景下，Swagger出現(xiàn)了(當然還有其他的就不一一例舉了)。

使用 Swagger 集成文檔具有以下幾個優(yōu)勢：

• 功能豐富 ：支持多種注解，自動生成接口文檔界面，支持在界面測試API接口功能
• 及時更新 ：開發(fā)過程中花一點寫注釋的時間，就可以及時的更新API文檔，省心省力
• 整合簡單 ：通過添加pom依賴和簡單配置，內(nèi)嵌于應用中就可同時發(fā)布API接口文檔界面，不需要部署獨立服務

開始整合Swagger2

在上一篇的項目基礎上，我們來使用一下Swagger。

1. 首先，我們需要在pom.xml中添加依賴,如下:

<!-- swagger、swagger-ui 依賴 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. 接下來我們來編寫一個SwaggerConfig配置類
   新建一個包:com.zhlab.demo.config,創(chuàng)建SwaggerConfig類
   SwaggerConfig.java

package com.zhlab.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @ClassName SwaggerConfig
 * @Description //SwaggerConfig配置類
 * @Author singleZhang
 * @Email 405780096@qq.com
 * @Date 2020/10/17 0017 上午 11:11
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {


    @Bean
    public Docket creatRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo())
                .select()
                //掃描指定路徑
                .apis(RequestHandlerSelectors.basePackage("com.zhlab.demo.controller"))
                // 掃描所有有注解的api，用這種方式更靈活
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 掃描所有
                // .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("zhLab Demo Api Doc")
                .description("api document of zhLab Demo")
                .version("1.0.1")
                .build();
    }

}

※說明:

• 在類上，添加 @EnableSwagger2 注解， 標記項目啟用 Swagger API 接口文檔。
• 通過 createRestApi() 方法，創(chuàng)建 Swagger Docket Bean
• 更多的配置可以在Docket.java、ApiInfo.java兩個類的源碼中查看

3. 修改上一篇中的HelloController控制器

package com.zhlab.demo.controller;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

/**
 * @ClassName HelloController
 * @Description //第一個Springboot接口
 * @Author singleZhang
 * @Email 405780096@qq.com
 * @Date 2020/10/16 0016 上午 10:55
 **/
@RestController
@RequestMapping("/system/user")
public class HelloController {

    /* 方法注解 */
    @ApiOperation(value = "方法名:打招呼", notes = "打招呼方法的測試")
    @GetMapping("/hello")
    public String sayHello(/* 參數(shù)注解 */ @ApiParam(value = "參數(shù):名字" , required=true ) @RequestParam String name){
        return "hi"+name+" ,I can say hello";
    }
}

啟動項目,在瀏覽器輸入http://localhost:8080/swagger-ui.html顯示下圖:

swagger-ui

TEST

常用注解說明

swagger 通過注解接口生成文檔，包括接口名，請求方法，參數(shù)，返回信息等。
@Api: 修飾整個類，用于controller類上
@ApiOperation: 描述一個接口，用戶controller方法上
@ApiParam: 單個參數(shù)描述
@ApiModel: 用來對象接收參數(shù),即返回對象
@ApiModelProperty: 對象接收參數(shù)時，描述對象的字段
@ApiResponse: Http響應其中的描述，在ApiResonse中
@ApiResponses: Http響應所有的描述，用在
@ApiIgnore: 忽略這個API
@ApiError: 發(fā)生錯誤的返回信息
@ApiImplicitParam: 一個請求參數(shù)
@ApiImplicitParam: 多個請求參數(shù)

總結

以上就是對Swagger的初步體驗,前后端分離api文檔是節(jié)省溝通成本的重要工具，用好它，你肯定會如虎添翼，以后還會推薦YAPI等工具。

項目地址

https://gitee.com/kaixinshow/springboot-note

返回【Spring Boot學習】目錄