swagger文档生成和测试

swagger2是一个在线生成文档和测试功能的软件，使用很简单，大概说一下步骤。

一、在pom中加入两个依赖：

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.2.2</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.2.2</version>

</dependency>

2、新建swagger配置类：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

     public class Swagger2 {
     
         @Bean
         public Docket createRestApi() {
             
             ParameterBuilder tokenPar = new ParameterBuilder();
             List<Parameter> pars = new ArrayList<>();
             tokenPar.name("Authorization").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
             pars.add(tokenPar.build());
     
             return new Docket(DocumentationType.SWAGGER_2)
                     .apiInfo(apiInfo())
                     .select()
                     .apis(RequestHandlerSelectors.basePackage("com.zp"))     //根据自己具体要扫描api的路径，就是接口路径。
                     .paths(PathSelectors.any())                   // 对所有路径进行监控
                     .build()
                     .globalOperationParameters(pars);
         }
     
         private ApiInfo apiInfo() {
             return new ApiInfoBuilder()
                     .title("Spring Boot中使用Swagger2构建RESTful APIs")
                     .description("springboot项目接口文档")
                     .termsOfServiceUrl("")
                     .contact("iamapsycho")
                     .version("1.0")
                     .build();
         }
     }
}
三、启动工程，访问localhost//swagger-ui.html即可。

四、具体使用

配置swagger还可以很精细，可以根据自己需要进行配置，比如扫描的具体包等。在代码中使用swagger功能，即可生成文档，具体百度很多。

1、@Api：请求类的说明：

       tags："说明该类的作用" 。value="该参数没什么意义，跟tags一样，所以不配置。

例子：@Api(tags = "消费分析")

2、@ApiOperation

      value：表示的是方法名称

      notes：表示的是方法描述，如接口描述

例子：@ApiOperation(value="商户热力地图",notes="热力地图，展示消费区域情况。")

3、@ApiImplicitParams：请求参数说明：

       name = 参数字符名称

       required ：参数是否必须
       dataType：参数类型，默认String，其它值dataType="int"

       value ：参数中文备注说明

例子：@ApiImplicitParams({
            @ApiImplicitParam(name = "unitCode", value = "99全部", required = false,
                    paramType = "query", dataType = "String")

4、返回参数实体类：

@ApiModel在实体类的方法上：

@ApiModelProperty：属性类的实体上面，属性上面，说明属性的含义。

@ApiModel(description= "返回响应数据") 

@ApiModelProperty(value = "是否成功")

5、返回约定（可以不写，约定写在公共文件头就行）：

@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明

        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

例子：

@ApiResponses({
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    }) 

注释：

可参考：https://blog.youkuaiyun.com/sanyaoxu_2/article/details/80555328