Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
更多关于Swagger的作用，相信大家百度一下能了解的更全面，本文以SpringBoot中集成Swagger为例做介绍说明。
一、修改pom.xml，添加maven依赖
<!-- Swagger -->
<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>
二、添加Swagger配置类
package com.example.swaggerdemo;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* SwaggerConfig
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* SpringBoot默认已经将classpath:/META-INF/resources/和classpath:/META-INF/resources/webjars/映射
* 所以该方法不需要重写，如果在SpringMVC中，可能需要重写定义（我没有尝试）
* 重写该方法需要 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/");
// }
/**
* 可以定义多个组，比如本类中定义把test和demo区分开了
* （访问页面就可以看到效果了）
*
*/
@Bean
public Docket testApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("test")
.genericModelSubstitutes(DeferredResult.class)
// .genericModelSubstitutes(ResponseEntity.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(true)
.pathMapping("/")// base，最终调用接口后会和paths拼接在一起
.select()
.paths(or(regex("/api/.*")))//过滤的接口
.build()
.apiInfo(testApiInfo());
}
@Bean
public Docket demoApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("demo")
.genericModelSubstitutes(DeferredResult.class)
// .genericModelSubstitutes(ResponseEntity.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(false)
.pathMapping("/")
.select()
.paths(or(regex("/demo/.*")))//过滤的接口
.build()
.apiInfo(demoApiInfo());
}
private ApiInfo testApiInfo() {
return new ApiInfoBuilder()
.title("Electronic Health Record(EHR) Platform API")//大标题
.description("EHR Platform's REST API, all the applications could access the Object model data via JSON.")//详细描述
.version("1.0")//版本
.termsOfServiceUrl("NO terms of service")
.contact(new Contact("小单", "http://blog.csdn.net/catoop", "365384722@qq.com"))//作者
.license("The Apache License, Version 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.build();
}
private ApiInfo demoApiInfo() {
return new ApiInfoBuilder()
.title("Electronic Health Record(EHR) Platform API")//大标题
.description("EHR Platform's REST API, all the applications could access the Object model data via JSON.")//详细描述
.version("1.0")//版本
.termsOfServiceUrl("NO terms of service")
.contact(new Contact("小单", "http://blog.csdn.net/catoop", "365384722@qq.com"))//作者
.license("The Apache License, Version 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.build();
return apiInfo;
}
}
经过这2步配置后，我们启动服务后，访问：http://localhost:8080/swagger-ui.html 就完成了集成。
Swagger会默认把所有Controller中的RequestMapping方法都生成API出来，实际上我们一般只需要标准接口的（像返回页面的那种Controller方法我们并不需要），所有你可以按下面的方法来设定要生成API的方法的要求。
如下我针对RestController注解的类和ResponseBody注解的方法才生成Swaager的API，并且排除了特定的类，代码如下：
@Configuration
@EnableSwagger2 // 启用 Swagger
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
Predicate<RequestHandler> predicate = new Predicate<RequestHandler>() {
@Override
public boolean apply(RequestHandler input) {
Class<?> declaringClass = input.declaringClass();
if (declaringClass == BasicErrorController.class)// 排除
return false;
if(declaringClass.isAnnotationPresent(RestController.class)) // 被注解的类
return true;
if(input.isAnnotatedWith(ResponseBody.class)) // 被注解的方法
return true;
return false;
}
};
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.useDefaultResponseMessages(false)
.select()
.apis(predicate)
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("包含媒体、咨询、搜索引擎关键字、广告等类型接口的服务")//大标题
.version("1.0")//版本
.build();
}
三、常见swagger注解一览与使用
最常用的5个注解
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
其它若干
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
下面创建2个Controller来测试：
1、TestController.java
@Controller
@RequestMapping("/api/test")
public class TestController {
@ResponseBody
@RequestMapping(value = "/show", method=RequestMethod.POST, produces=MediaType.APPLICATION_JSON_VALUE)// 这里指定RequestMethod，如果不指定Swagger会把所有RequestMethod都输出，在实际应用中，具体指定请求类型也使接口更为严谨。
@ApiOperation(value="测试接口", notes="测试接口详细描述")
public String show(
@ApiParam(required=true, name="name", value="姓名")
@RequestParam(name = "name", required=true) String stuName){
return "success";
}
}
2、DemoController.java
/**
* DemoController
*
*/
@Controller
@RequestMapping(value = "/demo")
public class DemoController {
private Logger logger = LoggerFactory.getLogger(DemoController.class);
/**
* 可以直接使用@ResponseBody响应JSON
*
* @param request
* @param response
* @return
*/
@ResponseBody
@RequestMapping(value = "/getcount", method = RequestMethod.POST)
@ApiOperation(value="测试-getCount", notes="getCount更多说明")
public ModelMap getCount(HttpServletRequest request,
HttpServletResponse response) {
logger.info(">>>>>>>> begin getCount >>>>>>>>");
ModelMap map = new ModelMap();
map.addAttribute("count", 158);
// 后台获取的国际化信息
map.addAttribute("xstest", "测试");
return map;
}
/**
* 可以直接使用@ResponseBody响应JSON
*
* @param request
* @param response
* @return
*/
@ApiIgnore//使用该注解忽略这个API
@ResponseBody
@RequestMapping(value = "/jsonTest1", method = RequestMethod.POST)
public ModelMap jsonTest(HttpServletRequest request,
HttpServletResponse response) {
ModelMap map = new ModelMap();
map.addAttribute("hello", "你好");
map.addAttribute("veryGood", "很好");
return map;
}
/**
* 可以直接使用@ResponseBody响应JSON
*
* @param request
* @param response
* @return
*/
@ResponseBody
@RequestMapping(value = "/jsonTest3", method = RequestMethod.POST)
public List<String> jsonTest3(HttpServletRequest request,
HttpServletResponse response) {
List<String> list = new ArrayList<String>();
list.add("hello");
list.add("你好");
return list;
}
/**
* JSON请求一个对象<br/>
* （Ajax Post Data：{"name":"名称","content":"内容"}）
*
* @param version
* @return
*/
@ResponseBody
@RequestMapping(value = "/jsonTest2", method = RequestMethod.POST)
public ModelMap jsonTest2(@RequestBody Demo demo) {
logger.info("demoName：" + demo.getName());
logger.info("demoContent：" + demo.getContent());
ModelMap map = new ModelMap();
map.addAttribute("result", "ok");
return map;
}
/**
* 直接读取URL参数值<br/>
* /demo/jsonTest6.do?name=Hello&content=World
*
* @param demoName
* @param content
* @return
*/
@ResponseBody
@RequestMapping(value = "/jsonTest6", method = RequestMethod.POST)
public ModelMap jsonTest6(@RequestParam("name") String demoName, @RequestParam String content) {
logger.info("demoName：" + demoName);
ModelMap map = new ModelMap();
map.addAttribute("name",demoName + "AAA");
map.addAttribute("content",content + "BBB");
map.addAttribute("date",new java.util.Date());
return map;
}
/**
* JSON请求一个对象，将RequestBody自动转换为JSONObject对象<br/>
* （Ajax Post Data：{"name":"名称","content":"内容"}）
*
* 使用JSONObject请添加依赖
* <dependency>
* <groupId>net.sf.json-lib</groupId>
* <artifactId>json-lib</artifactId>
* <version>2.4</version>
* <!--指定jdk版本 -->
* <classifier>jdk15</classifier>
* </dependency>
*
* @param version
* @return
*/
@ResponseBody
@RequestMapping(value = "/jsonTest5", method = RequestMethod.POST)
public ModelMap jsonTest5(@RequestBody JSONObject jsonObject) {
String name = jsonObject.getString("name");
logger.info("demoName：" + name);
ModelMap map = new ModelMap();
map.addAttribute("demoName",name);
return map;
}
/**
* 输入 和输出为JSON格式的数据的方式 HttpEntity<?> ResponseEntity<?>
*
* @param u
* @return
*/
@ResponseBody
@RequestMapping(value = "/jsonTest4", method = RequestMethod.POST)
public ResponseEntity<String> jsonTest4(HttpEntity<Demo> demo,
HttpServletRequest request, HttpSession session) {
//获取Headers方法
HttpHeaders headers = demo.getHeaders();
// 获取内容
String demoContent = demo.getBody().getContent();
// 这里直接new一个对象（HttpHeaders headers = new HttpHeaders();）
HttpHeaders responseHeaders = new HttpHeaders();
responseHeaders.add("MyHeaderName", "SHANHY");
ResponseEntity<String> responseResult = new ResponseEntity<String>(
demoContent, responseHeaders, HttpStatus.OK);
return responseResult;
}
}Swagger2默认将所有的Controller中的RequestMapping方法都会暴露，然而在实际开发中，我们并不一定需要把所有API都提现在文档中查看，这种情况下，使用注解@ApiIgnore来解决，如果应用在Controller范围上，则当前Controller中的所有方法都会被忽略，如果应用在方法上，则对应用的方法忽略暴露API。
注解@ApiOperation和@ApiParam可以理解为API说明，多动手尝试就很容易理解了。
如果我们不使用这样注解进行说明，Swagger2也是有默认值的，没什么可说的试试就知道了。
在 http://localhost:8080/swagger-ui.html 显示页面的右上角有api_key ，springfox-swagger 2.2.2 版本并没有进行处理，我们可以自己添加拦截器拦截 /v2/api-docs 来处理我们API文档的访问权限，如果要更严格更灵活的控制，可能需要修改源码来实现了。相信 springfox-swagger 的后期版本应该会支持更全面的应用需求的。
引自 http://blog.csdn.net/catoop/article/details/50668896