swagger2 Api文档配置

一、Swagger2介绍

前后端分离开发模式中，api文档是最好的沟通方式。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

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

二、配置

第一步：引入依赖

<!--swagger-->
<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>

第二部：配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }
    
    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("***标题***")
                .description("***网站描述***")
                .version("1.0")
                .contact(new Contact("Helen", "网站首页网址", "联系方式@qq.com"))
                .build();
    }
}

第三步（可选）：可用注解

在controller类或者实体类添加接口注解

注解解释：
　　- @Api()用于类；
　　　　　　表示标识这个类是swagger的资源
　　- @ApiOperation()用于方法；
　　　　　　表示一个http请求的操作
　　- @ApiParam()用于方法，参数，字段说明；
　　　　　　表示对参数的添加元数据（说明或是否必填等）
　　- @ApiModel()用于类
　　　　　　表示对类进行说明，用于参数用实体类接收
　　- @ApiModelProperty()用于方法，字段
　　　　　　表示对model属性的说明或者数据操作更改
　　- @ApiIgnore()用于类，方法，方法参数
　　　　　　表示这个方法或者类被忽略
　　- @ApiImplicitParam() 用于方法
　　　　　　表示单独的请求参数
　　- @ApiImplicitParams() 用于方法，包含多个@ApiImplicitParam

当然还有很多，具体自己要用到在查

第四步：访问Api

访问地址：

springboot项目是：http://localhost:端口号/swagger-ui.html
非springboot项目：==http://localhost:端口号/项目名称/swagger-ui.html ==