SpringBoot2.0集成Swagger2，生成RESTful API在线文档接口

什么是swagger

swagger是一个流行的API开发框架，这个框架以“开放式API声明”（OpenAPI Specification，OAS）为基础，对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。

OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是GET还是POST请求啊，有哪些参数哪些header啊，都会被包括在这个文件中。它在设计的时候通常是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多，因为json的通用性比较强。

由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来，同时springfox也是一个新的项目，本文仍然是使用其中的一个组件springfox-swagger2。

pringfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件，我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来。

swagger2相关依赖

		<dependency>
		    <groupId>io.springfoxgroupId>
		    <artifactId>springfox-swagger2artifactId>
		    <version>2.8.0version>
		dependency>
		<dependency>
		    <groupId>io.springfoxgroupId>
		    <artifactId>springfox-swagger-uiartifactId>
		    <version>2.8.0version>
		dependency>

当然，一般需要用到json相关的依赖，fastjson/gson/jackson都可以，这里当然推荐阿里巴巴的FastJson，晚点会有文章专门介绍。

如果@EnableSwagger2一直无效，应该是maven有问题，删除C:\Users\Administrator.m2\repository\io\springfox\springfox-swagger2\2.8.0目录，重新maven build加参数clean compile运行pom.xml即可。

接下来是springboot2.0的swagger2配置

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 SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.microservice.tcbj.yytsg.checkcentersys"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("营养探索馆-客服系统")
                .description("powered by By-Health")
                .termsOfServiceUrl("http://www.by-health.com/")
                //.contact(contact)
                .version("1.0")
                .build();
    }

}

添加文档内容

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParam注解来给参数增加说明。

@Api("客服接口")
@Controller
@RequestMapping("/checkcenter")
public class CheckCenterController {

	
	@ApiOperation(value="获取客服", notes="根据cid获取客服")
    @ApiImplicitParam(name = "cid", value = "客户id", required = true, dataType = "String")
	@ResponseBody
	@GetMapping("/getCenter")
	public ApiReturnObject getCenter(String cid) {
		Map<String,String> map=new LinkedHashMap<String,String>();
		map.put("cid",cid);
		map.put("name","客服");
		return ApiReturnUtil.success(map);
	}
	
	@ApiOperation(value="获取客服", notes="根据cid获取客服")
    @ApiImplicitParam(name = "cid", value = "客户id", required = true, dataType = "String")
	@ResponseBody
	@PostMapping("/getCenter/{cid}")
	public ApiReturnObject getCenter2(@PathVariable String cid) {
		Map<String,String> map=new LinkedHashMap<String,String>();
		map.put("cid",cid);
		map.put("name","客服");
		return ApiReturnUtil.success(map);
	}
}

访问swagger查看效果

一般是直接访问项目/swagger-ui.html就可以了
http://localhost:8080/swagger-ui.html
例如我配置了

server:
    port: 8083
    servlet:
        context-path: /checkcentersys

那我要访问的是
http://localhost:8083/checkcentersys/swagger-ui.html

swagger效果

接口情况就有了

更详细的情况可以点进去接口查看，并且可以"try it out"，这个比postman调起来就方便多了。

访问与安全

一般swagger需要一下api的权限，需要在对应的模块进行排除
http://localhost:8080/swagger-resources/configuration/ui
http://localhost:8080/swagger-resources
http://localhost:8080/api-docs
http://localhost:8080/swagger-ui.html
http://localhost:8080/swagger-resources/configuration/security

如果项目上线并且需要关闭swagger接口，可以通过配置权限，或者再SwaggerConfig里面
return new Docket的时候加多一个.enable(false)