APi接口文档：Swagger2 介绍

这是我参与更文挑战的第1天，活动详情查看： 更文挑战

一、Swagger2 介绍

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

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

• 及时性（接口变更后，能够及时准确的通知前后端开发人员）
• 规范性（并且保证接口的规范性，如接口的地址，请求方式，参数，响应格式和错误信息）
• 一致性（接口信息一致，不糊出现文档版本不一致产生分歧）
• 可测性（直接在接口文档上进行测试）

二、 配置文件

1、依赖：

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
复制代码

2、配置类：

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2);
    }
}
复制代码

3、配置config

@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * web端
     *  给命名然后过滤接口。
     * @return
     */
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/api/.*"))).build();
    }

    /**
     * 后台管理端
     * @return
     */
    @Bean
    public Docket adminApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/admin/.*"))).build();
    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder().title("网站的API文档")
                .description("本文档描述了潇雷视频网的api接口定义")
                .version("1.0")
                .contact(new Contact("xiaolei","https://juejin.cn/user/96412756360526","***@qq.com"))
                .build();
    }
    private ApiInfo adminApiInfo(){
        return new ApiInfoBuilder().title("后台管理系统的API文档")
                .description("本文档描述了潇雷视频网的后台管理端api接口定义")
                .version("1.0")
                .contact(new Contact("xiaolei","https://juejin.cn/user/96412756360526","****@qq.com"))
                .build();
    }
}
复制代码

三、常见注解

3.1 API模型

entity的实体类中可以添加一些自定义设置，例如：

    @ApiModelProperty(value = "入驻时间",example = "2021-05-31")
    @JsonFormat(timezone = "GMT+8",pattern = "yyyy-MM-dd")
    private Date joinDate;
复制代码

3.2 定义接口说明和参数说明

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
• @ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

@Api(description = "讲师管理")
@ApiOperation(value = "根据id删除讲师",notes = "逻辑删除")
复制代码