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相关依赖

<!-- swagger2 -->
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
		    <version>2.8.0</version>
		</dependency>
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger-ui</artifactId>
		    <version>2.8.0</version>
		</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)