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("数据不存在");
    }
}

测试