配置 Swagger2 接口文檔引擎

學(xué)習(xí)完整課程請移步互聯(lián)網(wǎng) Java 全棧工程師

本節(jié)視頻

【視頻】Spring Cloud Alibaba-MyShop-Swagger2 接口文檔引擎

手寫文檔存在的問題

文檔需要更新的時候蟆肆，需要再次發(fā)送一份給前端谨读，也就是文檔更新交流不及時。
接口返回結(jié)果不明確
不能直接在線測試接口钻趋，通常需要使用工具烧董，比如：Postman
接口文檔太多毁靶，不好管理

使用 Swagger 解決問題

Swagger 也就是為了解決這個問題，當(dāng)然也不能說 Swagger 就一定是完美的逊移，當(dāng)然也有缺點(diǎn)预吆，最明顯的就是代碼植入性比較強(qiáng)。

Maven

增加 Swagger2 所需依賴胳泉，pom.xml 配置如下：

<!-- Swagger2 Begin -->
<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>
<!-- Swagger2 End -->

配置 Swagger2

注意：RequestHandlerSelectors.basePackage("com.funtl.myshop.service") 為 Controller 包路徑拐叉，不然生成的文檔掃描不到接口

創(chuàng)建一個名為 Swagger2Configuration 的 Java 配置類，代碼如下：

package com.funtl.myshop.commons.service.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;

@Configuration
public class Swagger2Configuration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.funtl.myshop.service"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("MyShop API 文檔")
                .description("MyShop API 網(wǎng)關(guān)接口胶背，http://www.funtl.com")
                .termsOfServiceUrl("http://www.funtl.com")
                .version("1.0.0")
                .build();
    }
}

啟用 Swagger2

Application 中加上注解 @EnableSwagger2 表示開啟 Swagger

package com.funtl.myshop.service.reg;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.stream.annotation.EnableBinding;
import org.springframework.cloud.stream.messaging.Source;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.scheduling.annotation.EnableAsync;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import tk.mybatis.spring.annotation.MapperScan;

@SpringBootApplication
@EnableDiscoveryClient
@ComponentScan(basePackages = "com.funtl.myshop")
@MapperScan(basePackages = "com.funtl.myshop.commons.mapper")
@EnableBinding({Source.class})
@EnableAsync
@EnableSwagger2
public class MyShopServiceRegApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyShopServiceRegApplication.class, args);
    }
}

使用 Swagger2

在 Controller 中增加 Swagger2 相關(guān)注解巷嚣，代碼如下：

/**
 * 用戶注冊
 *
 * @param tbUser
 * @return
 */
@ApiOperation(value = "用戶注冊", notes = "以實(shí)體類為參數(shù)喘先，注意用戶名和郵箱不要重復(fù)")
@PostMapping(value = {""})
public AbstractBaseResult reg(@ApiParam(name = "tbUser", value = "用戶模型") TbUser tbUser) {
    // 數(shù)據(jù)校驗(yàn)
    AbstractBaseResult validator = validator(tbUser);
    if (validator != null) {
        return validator;
    }

    // 判斷用戶名是否重復(fù)
    if (!tbUserService.unique("username", tbUser.getUsername())) {
        return error("用戶名重復(fù)钳吟，請重試", null);
    }

    // 判斷郵箱是否重復(fù)
    if (!tbUserService.unique("email", tbUser.getEmail())) {
        return error("郵箱重復(fù)，請重試", null);
    }

    // 設(shè)置密碼加密
    if (StringUtils.isNotBlank(tbUser.getPassword())) {
        tbUser.setPassword(DigestUtils.md5DigestAsHex(tbUser.getPassword().getBytes()));
    }

    // 密碼為空
    else {
        return error("密碼不可為空", null);
    }

    // 注冊用戶
    TbUser user = tbUserService.save(tbUser);
    if (user != null) {
        response.setStatus(HttpStatus.CREATED.value());
        // 發(fā)送注冊成功通知到消息隊列
        regService.sendEmail(user);
        return success(request.getRequestURI(), user);
    }

    return error("注冊失敗窘拯，請重試", null);
}

訪問 Swagger2

訪問地址：http://ip:port/swagger-ui.html

Swagger 常用注解說明

Swagger 通過注解表明該接口會生成文檔红且，包括接口名、請求方法涤姊、參數(shù)暇番、返回信息的等等。

常用注解

@Api：修飾整個類思喊，描述 Controller 的作用
@ApiOperation：描述一個類的一個方法壁酬，或者說一個接口
@ApiParam：單個參數(shù)描述
@ApiModel：用對象來接收參數(shù)
@ApiProperty：用對象接收參數(shù)時，描述對象的一個字段
@ApiResponse：HTTP 響應(yīng)其中 1 個描述
@ApiResponses：HTTP 響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個API
@ApiError：發(fā)生錯誤返回的信息
@ApiImplicitParam：一個請求參數(shù)
@ApiImplicitParams：多個請求參數(shù)

`@Api`

說明：用在請求的類上恨课，表示對類的說明

常用參數(shù)：

tags="說明該類的作用舆乔，非空時將覆蓋 value 的值"
value="描述類的作用"

其他參數(shù)：

description 對 api 資源的描述，在 1.5 版本后不再支持
basePath 基本路徑可以不配置剂公，在 1.5 版本后不再支持
position 如果配置多個 Api 想改變顯示的順序位置希俩，在 1.5 版本后不再支持
produces 設(shè)置 MIME 類型列表（output），例："application/json, application/xml"纲辽，默認(rèn)為空
consumes 設(shè)置 MIME 類型列表（input）颜武，例："application/json, application/xml"璃搜，默認(rèn)為空
protocols 設(shè)置特定協(xié)議，例：http鳞上， https这吻， ws， wss
authorizations 獲取授權(quán)列表（安全聲明）篙议，如果未設(shè)置橘原，則返回一個空的授權(quán)值。
hidden 默認(rèn)為 false涡上，配置為 true 將在文檔中隱藏

示例：

@Api(tags="登錄請求")
@Controller
public class LoginController {}

`@ApiOperation`

說明：用在請求的方法上趾断，說明方法的用途、作用

常用參數(shù)：

value="說明方法的用途吩愧、作用"
notes="方法的備注說明"

其他參數(shù)：

tags 操作標(biāo)簽芋酌，非空時將覆蓋value的值
response 響應(yīng)類型（即返回對象）
responseContainer 聲明包裝的響應(yīng)容器（返回對象類型）。有效值為 "List", "Set" or "Map"雁佳。
responseReference 指定對響應(yīng)類型的引用脐帝。將覆蓋任何指定的response（）類
httpMethod 指定HTTP方法，"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
position 如果配置多個Api 想改變顯示的順序位置糖权，在1.5版本后不再支持
nickname 第三方工具唯一標(biāo)識堵腹，默認(rèn)為空
produces 設(shè)置MIME類型列表（output），例："application/json, application/xml"星澳，默認(rèn)為空
consumes 設(shè)置MIME類型列表（input）疚顷，例："application/json, application/xml"，默認(rèn)為空
protocols 設(shè)置特定協(xié)議禁偎，例：http腿堤， https， ws如暖， wss笆檀。
authorizations 獲取授權(quán)列表（安全聲明），如果未設(shè)置盒至，則返回一個空的授權(quán)值酗洒。
hidden 默認(rèn)為false，配置為true 將在文檔中隱藏
responseHeaders 響應(yīng)頭列表
code 響應(yīng)的HTTP狀態(tài)代碼枷遂。默認(rèn) 200
extensions 擴(kuò)展屬性列表數(shù)組

示例：

@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登錄檢測", notes="根據(jù)用戶名樱衷、密碼判斷該用戶是否存在")
public UserModel login(@RequestParam(value = "name", required = false) String account,
@RequestParam(value = "pass", required = false) String password){}

`@ApiImplicitParams`

說明：用在請求的方法上，表示一組參數(shù)說明登淘；@ApiImplicitParam：用在 @ApiImplicitParams 注解中箫老，指定一個請求參數(shù)的各個方面

常用參數(shù)：

name：參數(shù)名，參數(shù)名稱可以覆蓋方法參數(shù)名稱黔州，路徑參數(shù)必須與方法參數(shù)一致
value：參數(shù)的漢字說明耍鬓、解釋
required：參數(shù)是否必須傳阔籽，默認(rèn)為 false （路徑參數(shù)必填）
paramType：參數(shù)放在哪個地方
- header 請求參數(shù)的獲取：@RequestHeader
- query 請求參數(shù)的獲壬瘛：@RequestParam
- path（用于 restful 接口）--> 請求參數(shù)的獲劝手啤：@PathVariable
- body（不常用）
- form（不常用）
dataType：參數(shù)類型，默認(rèn) String涣达，其它值 dataType="Integer"
defaultValue：參數(shù)的默認(rèn)值

其他參數(shù)（@ApiImplicitParam）：

allowableValues 限制參數(shù)的可接受值在辆。1.以逗號分隔的列表 2.范圍值 3.設(shè)置最小值/最大值
access 允許從API文檔中過濾參數(shù)。
allowMultiple 指定參數(shù)是否可以通過具有多個事件接受多個值度苔，默認(rèn)為 false
example 單個示例
examples 參數(shù)示例匆篓。僅適用于 BodyParameters

示例：

@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登錄檢測", notes="根據(jù)用戶名、密碼判斷該用戶是否存在")
@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "用戶名", required = false, paramType = "query", dataType = "String"),
    @ApiImplicitParam(name = "pass", value = "密碼", required = false, paramType = "query", dataType = "String")
})
public UserModel login(@RequestParam(value = "name", required = false) String account,
@RequestParam(value = "pass", required = false) String password){}

`@ApiModel`

說明：用于響應(yīng)類上寇窑，表示一個返回響應(yīng)數(shù)據(jù)的信息（這種一般用在 POST 創(chuàng)建的時候鸦概，使用 @RequestBody 這樣的場景，請求參數(shù)無法使用 @ApiImplicitParam 注解進(jìn)行描述的時候）甩骏；@ApiModelProperty：用在屬性上窗市，描述響應(yīng)類的屬性

其他參數(shù)(@ApiModelProperty)：

value 此屬性的簡要說明。
name 允許覆蓋屬性名稱
allowableValues 限制參數(shù)的可接受值饮笛。1.以逗號分隔的列表 2.范圍值 3.設(shè)置最小值/最大值
access 允許從 API 文檔中過濾屬性咨察。
- notes 目前尚未使用。
dataType 參數(shù)的數(shù)據(jù)類型福青∩阌可以是類名或者參數(shù)名，會覆蓋類的屬性名稱素跺。
required 參數(shù)是否必傳二蓝，默認(rèn)為 false
position 允許在類中對屬性進(jìn)行排序誉券。默認(rèn)為 0
hidden 允許在 Swagger 模型定義中隱藏該屬性指厌。
example 屬性的示例。
readOnly 將屬性設(shè)定為只讀踊跟。
reference 指定對相應(yīng)類型定義的引用踩验，覆蓋指定的任何參數(shù)值

示例：

@ApiModel(value="用戶登錄信息", description="用于判斷用戶是否存在")
public class UserModel implements Serializable{

   private static final long serialVersionUID = 1L;

   /**
    * 用戶名
    */
   @ApiModelProperty(value="用戶名")
   private String account;

   /**
     * 密碼
     */
    @ApiModelProperty(value="密碼")
   private String password;
}

`@ApiResponses`

說明：用在請求的方法上，表示一組響應(yīng)商玫；@ApiResponse：用在 @ApiResponses 中箕憾，一般用于表達(dá)一個錯誤的響應(yīng)信息

常用參數(shù)：

code：數(shù)字，例如 400
message：信息拳昌，例如 "請求參數(shù)沒填好"
response：拋出異常的類

示例：

@ResponseBody
@PostMapping(value="/update/{id}")
@ApiOperation(value = "修改用戶信息",notes = "打開頁面并修改指定用戶信息")
@ApiResponses({
    @ApiResponse(code=400,message="請求參數(shù)沒填好"),
    @ApiResponse(code=404,message="請求路徑?jīng)]有或頁面跳轉(zhuǎn)路徑不對")
})
public JsonResult update(@PathVariable String id, UserModel model){}

`@ApiParam`

說明：用在請求方法中袭异，描述參數(shù)信息

常用參數(shù)：

name：參數(shù)名稱，參數(shù)名稱可以覆蓋方法參數(shù)名稱炬藤，路徑參數(shù)必須與方法參數(shù)一致
value：參數(shù)的簡要說明御铃。
defaultValue：參數(shù)默認(rèn)值
required：屬性是否必填碴里，默認(rèn)為 false （路徑參數(shù)必須填）

以實(shí)體類為參數(shù)：

@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登錄檢測", notes="根據(jù)用戶名、密碼判斷該用戶是否存在")
public UserModel login(@ApiParam(name = "model", value = "用戶信息Model") UserModel model){}

其他參數(shù)：

allowableValues 限制參數(shù)的可接受值上真。1.以逗號分隔的列表 2.范圍值 3.設(shè)置最小值/最大值
access 允許從 API 文檔中過濾參數(shù)咬腋。
allowMultiple 指定參數(shù)是否可以通過具有多個事件接受多個值，默認(rèn)為 false
hidden 隱藏參數(shù)列表中的參數(shù)睡互。
example 單個示例
examples 參數(shù)示例根竿。僅適用于 BodyParameters

示例：

@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登錄檢測", notes="根據(jù)用戶名、密碼判斷該用戶是否存在")
public UserModel login(@ApiParam(name = "name", value = "用戶名", required = false) @RequestParam(value = "name", required = false) String account,
    @ApiParam(name = "pass", value = "密碼", required = false) @RequestParam(value = "pass", required = false) String password){}