Swagger2介绍

阳光穿透心脏的1/2处 2021-07-24 11:45 358阅读 0赞

# 一  Swagger2介绍 #

官网：[https://swagger.io/][https_swagger.io]

前后端分离开发模式中，api文档是最好的沟通方式。

*  前端工程师编写接口文档（使用swagger2编辑器或其他接口生成工具）
 *  交给后端工程师
 *  根据swagger文档编写后端接口
 *  最终根据生成的swagger文件进行接口联调

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

*  及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
 *  规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
 *  一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
 *  可测性 (直接在接口文档上进行测试，以方便理解业务)

# 二 配置 Swagger2 #

1 依赖

<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][http_localhost_8110_swagger-ui.html]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2NoZW5ncWl1bWluZw_size_16_color_FFFFFF_t_70][]

# 三 常见注解 #

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

测试

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2NoZW5ncWl1bWluZw_size_16_color_FFFFFF_t_70 1][]

[https_swagger.io]: https://swagger.io/
[http_localhost_8110_swagger-ui.html]: http://localhost:8110/swagger-ui.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2NoZW5ncWl1bWluZw_size_16_color_FFFFFF_t_70]: /images/20210724/c4d6f1e288c34706ab6e6f6ffb9e2303.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2NoZW5ncWl1bWluZw_size_16_color_FFFFFF_t_70 1]: /images/20210724/ada0095923dc490dacc61faa5088f35e.png