Swagger2的使用和配置

1.简介

        帮助前端开发人员便捷调用后端api的，减少不必要的沟通联调，自动生成接口文档，并且也可以像postman一样发送https请求的一款自带UI的插件

2.注解

@Api()：用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

参数：

tags：说明该类的作用，参数是个数组，可以填多个。
value="该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"

@ApiOperation()：用于方法，表示一个http请求访问该方法的操作

参数：

value="方法的用途和作用"    
notes="方法的注意事项和备注"    
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={"作用1","作用2"} 
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

@ApiModel()：用于响应实体类上，用于说明实体作用

参数：

description="描述实体的作用"  

@ApiModelProperty：用在属性上，描述实体类的属性

参数：

value="用户名"  描述参数的意义
name="name"    参数的变量名
required=true     参数是否必选

@ApiImplicitParams：用在请求的方法上，包含多@ApiImplicitParam

@ApiImplicitParam：用于方法，表示单独的请求参数

参数：

name="参数ming" 
value="参数说明" 
dataType="数据类型" 
paramType="query" 表示参数放在哪里
    · header 请求参数的获取：@RequestHeader
    · query   请求参数的获取：@RequestParam
    · path（用于restful接口） 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用） 
defaultValue="参数的默认值"
required="true" 表示参数是否必须传

@ApiParam()：用于方法，参数，字段说明 表示对参数的要求和说明

参数：

name="参数名称"
value="参数的简要说明"
defaultValue="参数默认值"
required="true" 表示属性是否必填，默认为false

@ApiResponses：用于请求的方法上，根据响应码表示不同响应

一个@ApiResponses包含多个@ApiResponse

@ApiResponse：用在请求的方法上，表示不同的响应

参数：

code="404"    表示响应码(int型)，可自定义
message="状态码对应的响应信息"   

@ApiIgnore()：用于类或者方法上，不被显示在页面上

 3.配置

步骤1:pom文件导入依赖

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

步骤2：启动类添加@EnableSwagger2注解

@SpringBootApplication
@EnableSwagger2
@ComponentScan(basePackages = {""})
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }
}

步骤3:编写SwaggerConfig文件

@EnableSwagger2
@Configuration
public class SwaggerConfig implements WebMvcConfigurer {

    /**
    * apiInfo() 增加API相关信息
    * 所有的注解
    * .apis(RequestHandlerSelectors.any()) 
    * 指定部分注解1.Api.class(@APi),2.ApiOperation.class(@ApiOperation),3.ApiImplicitParam.class(@ApiImplicitParam)
    *.apis(RequestHandlerSelectors.withMethodAnnotation(Api.class))
    * 指定包路径
    * .apis(RequestHandlerSelectors.basePackage("这里填写需要的路径"))
    * .paths() 这个是包路径下的路径,PathSelectors.any()是包下所有路径
    */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                //创建
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成")
                .description("springboot | swagger")
                // 作者信息
                .contact(new Contact("kacen", "https://www.baidu.com", "abc@qq.com"))
                .version("0.0.1")
                .build();
    }

}

步骤4:输入http://服务器ip:端口/swagger-ui.html 看接口文档吧