swagger2的使用详解

1、添加Swagger2依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

2、创建Swagger2配置类

在XXXApplication.java同级目录创建类Swagger2，basePackage指定将生成文档的接口路径。

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

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.springcloudproducer"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springcloudproducer_RESTful APIs")
                .description("服务名：springcloudproducer")
                .version("1.0")
                .build();
    }
}

3、接口使用

@ApiOperation(value = "invoke", notes = "invoke测试")
@ApiImplicitParam(name = "param", value = "invoke入参", required = true, dataType = "String", paramType = "query")
@GetMapping(value = "/invoke")
public String invoke(String param) {
    System.out.println("This springCloudConsumerService 1:" + param);
    String result = param + "_consumer_" + System.currentTimeMillis();
    return result;
}

Note：
方法注释必须指定请求类型，否则swagger2将会生成该方法的各种请求类型的文档。

【=示例 start=】：

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping(value = "/api")
public class SpringCloudConsumerController {
    @Autowired
    private IQueryService queryService;

    @ApiOperation(value = "invoke", notes = "invoke测试")
    @ApiImplicitParam(name = "param", value = "invoke入参", required = true, dataType = "String", paramType = "query")
    @GetMapping(value = "/invoke")
    public String invoke(String param) {
        System.out.println("This springCloudConsumerService 1:" + param);
        String result = param + "_consumer_" + System.currentTimeMillis();
        return result;
    }
    
    @ApiOperation(value = "线程池环境测试跟踪ID", notes = "TraceThreadPoolExecutor测试跟踪ID")
    @ApiImplicitParam(name = "param", value = "入参", required = true, dataType = "String", paramType = "query")
    @PostMapping(value = "/testTrackID_C")
    public String testTrackID(@RequestParam(value = "param") String param) {
        String result = queryService.testTrackID(param);
        return result;
    }
}

【=示例 end=】

如果参数（返回值）是对象且需要@ApiModel，那么类（及基类）都需要加注解@ApiModel。否则接口A展示的Swagger对象信息可能是接口B的Swagger对象信息（猜测是swagger的bug）。

4、访问swagger管理页面

访问 http://localhost:port/swagger-ui.html，看到如下界面即表示成功。
填入相应参数，点击Try it out!即可进行接口测试。

5、Swagger使用的注解及其说明

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在出入参数对象的字段上
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

@ApiImplicitParam

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交 仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交 仅支持POST
dataType		参数的数据类型 只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true
	false	非必填
defaultValue		默认值

6、异常处理

若swagger2页面空白，
相关依赖：

<java.version>1.8</java.version>
<spring-cloud.version>Edgware.SR1</spring-cloud.version>

<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.10.RELEASE</version>

解决方案：
在Swagger2同级目录新建WebMvcConfig类，

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

若页面依旧是空白，则修改springfox-swagger2、springfox-swagger-ui版本，此处均降级为2.6.1版本即可。

Swagger相关注解官方使用文档：
https://springfox.github.io/springfox/docs/current/#overriding-descriptions-via-properties
https://springfox.github.io/springfox/docs/current/#property-file-lookup

@Api:

不使用value，使用tags，和description,不公布TokenController
@Api(description = “接口描述”,tags = {“接口tags”})

@ApiModelProperty：

• required = false：Swagger将展示成optional，optional表示可选。
• allowableValues = “1,2,3”,：Swagger将展示 = [‘1’, ‘2’, ‘3’],表示枚举值；
• readOnly = true：表示只读，Swagger将展示read only。、，具体功用待定；
• hidden = true：表示隐藏该属性，Swagger将不展示该属性；
• value = “差旅开放平台系统应用APPSecret”：表示字段描述；
• position = 1：表示将字段排在第2位，默认按代码顺序排序；
• example = "example：表示默认值，是Swagger生成Example Value时的默认值，方便Swagger测试使用，不是接口调用时的默认值。