Swagger入门

一、swagger的作用

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。**其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。**但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

二、Swagger文档模板

三、使用swagger

1.导入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.配置swagger

@Configuration //<beans></beans>
@EnableSwagger2//开启swagger
public class SwaggerConfig {
  
}

3.自定义swagger配置

  @Bean	//配置swagger的Docket对象
    public Docket getDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//使用自己写的swagger的显示信息
                .useDefaultResponseMessages(false)//是否使用默认的响应信息
                .select()//初始化controller包
//                .paths(Predicates.or(PathSelectors.regex("/api2.*")))//过滤，声明不生成api文档的路径
                .build();
    }
    //配置swagger的API文档信息
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("工程管理项目API文档")
                .description("菜单模块、角色模块、用户模块、工程管理模块")
                .version("1.0")
                .contact(new Contact("charlotte","https://space.bilibili.com/84466353","2019547086@qq.com"))//构建联系方式的对象（作者信息）
                .license("本人许可")
                .licenseUrl("许可证url：http:www.baidu.com")
                .build();
    }

四、扫描实体类

只要在controller的方法中返回实体类，则该类会被扫描到接口文档中

五、常用注解

1.@Api（description = ""）

​ 是注释注解的老大，用于标注一个Controller或者Class，通常用于标注controller。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

2.@ApiModel(description = "这是用户实体类",value = "user实体类")**

​ 给实体类添加注释

3.@ApiModelProperty(value = "名字")

​ 给实体类属性添加注释

4.@ApiOperation(value = "方法的注释")

​ 给方法添加注释

5.@ApiParam(value = "名字") String name

​ 给参数添加注释

六、分组

.groupName("默认")

分多个组

@Bean
public Docket getDefaultDocket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())//swagger的信息
            .enable(true)//是否启动swagger。如果参数为false，则不能在浏览器中访问
            .groupName("默认")
            .useDefaultResponseMessages(true) //使用默认的响应模板
            .select()
            .build();
}
    @Bean
    public Docket getDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//swagger的信息
                .enable(true)//是否启动swagger。如果参数为false，则不能在浏览器中访问
                .groupName("pfk")
                .useDefaultResponseMessages(true) //使用默认的响应模板
                .select()
//                .paths(PathSelectors.ant("com.baidu.kaikai/*"))
                .apis(RequestHandlerSelectors.basePackage("com.baidu.kaikai") )
                .build();
    }