Swagger2介紹

一  Swagger2介紹

官網：https://swagger.io/

先後端分離開發模式中，api文檔是最好的溝通方式。

• 前端工程師編寫接口文檔（使用swagger2編輯器或其餘接口生成工具）

• 交給後端工程師

• 根據swagger文檔編寫後端接口

• 最終根據生成的swagger文件進行接口聯調

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。

• 及時性 (接口變動後，可以及時準確地通知相關先後端開發人員)

• 規範性 (而且保證接口的規範性，如接口的地址，請求方式，參數及響應格式和錯誤信息)

• 一致性 (接口信息一致，不會出現因開發人員拿到的文檔版本不一致，而出現分歧)

• 可測性 (直接在接口文檔上進行測試，以方便理解業務)

二 配置 Swagger2

1 依賴

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>

2 建立Swagger2配置文件

在service_base中建立Swatter2Config的配置文件

@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * 功能描述：網站api的配置
     *
     * @return Docket 網站api的配置
     * @author cakin
     * @date 2020/11/16
     */
    @Bean
    public Docket webApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi") // 組名
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/api/.*"))) // 過濾的URL地址
                .build();
    }
    /**
     * 功能描述：後臺api的配置
     *
     * @return Docket 後臺api的配置
     * @author cakin
     * @date 2020/11/16
     */
    @Bean
    public Docket adminApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi") // 組名
                .apiInfo(adminApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/admin/.*"))) // 過濾的URL地址
                .build();
    }

    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder()
                .title("網站的API文檔") // 標題
                .description("本文檔描述了穀粒學院網站的api接口定義") // 描述
                .version("1.0") // 版本
                .contact(new Contact("cakin", "http://atguigu.com", "798103175@qq.com")) // 聯繫人
                .build();
    }

    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder()
                .title("後臺管理系統的API文檔") // 標題
                .description("本文檔描述了穀粒學院後臺管理系統的api接口定義") // 描述
                .version("1.0") // 版本
                .contact(new Contact("Helen", "http://atguigu.com", "798103175@qq.com")) // 聯繫人
                .build();
    }
}

3 重啓服務器查看接口

http://localhost:8110/swagger-ui.html

三 常見註解

1 API模型

entity的實體類中能夠添加一些自定義設置。

@Data
@EqualsAndHashCode(callSuper = true)
@Accessors(chain = true)
@TableName("edu_teacher")
@ApiModel(value = "Teacher對象", description = "講師") // 類級別Swagger的描述，value來自數據庫，由Mybatis-plus逆向生成
public class Teacher extends BaseEntity {
    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "講師姓名", example = "周老師") // 屬性級別Swagger的描述，value來自數據庫，由Mybatis-plus逆向生成
    private String name;

    @ApiModelProperty(value = "講師簡介")
    private String intro;

    @ApiModelProperty(value = "講師資歷,一句話說明講師")
    private String career;

    @ApiModelProperty(value = "頭銜 1高級講師 2首席講師")
    private Integer level;

    @ApiModelProperty(value = "講師頭像")
    private String avatar;

    @ApiModelProperty(value = "排序")
    private Integer sort;

    @ApiModelProperty(value = "入駐時間", example = "2020-01-01") // 屬性級別Swagger的描述,example舉個例子，便於理解
    @JsonFormat(timezone = "GMT+8", pattern = "yyyy-MM-dd")
    private Date joinDate;

    @ApiModelProperty(value = "邏輯刪除 1（true）已刪除， 0（false）未刪除")
    @TableField("is_deleted")
    @TableLogic
    private Boolean deleted;
}

2 定義接口說明和參數說明

定義在類上：@Api

定義在方法上：@ApiOperation

定義在參數上：@ApiParam

// @ApiOperation:定義在方法上
@ApiOperation("全部講師列表")
@GetMapping("list")
public R listAll() {
    List<Teacher> list = teacherService.list();
    return R.ok().data("items", list);
}


// @ApiOperation:定義在方法上
@ApiOperation(value = "根據ID刪除講師", notes = "根據ID刪除講師，邏輯刪除")
@DeleteMapping("remove/{id}")
// @ApiParam：定義在參數上
public R removeById(@ApiParam(value = "講師ID", required = true) @PathVariable String id) {
    boolean result = teacherService.removeById(id);
    if (result) {
        return R.ok().message("刪除成功");
    } else {
        return R.error().message("數據不存在");
    }
}

測試