Spring Boot 集成Swagger

krna7328 4年前

来自: http://blog.csdn.net/catoop/article/details/50668896

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

更多关于Swagger的作用,相信大家百度一下能了解的更全面,本文以SpringBoot中集成Swagger为例做介绍说明。

一、修改pom.xml,添加maven依赖

        <!-- Swagger -->          <dependency>              <groupId>io.springfox</groupId>              <artifactId>springfox-swagger-ui</artifactId>              <version>2.2.2</version>          </dependency>            <dependency>              <groupId>io.springfox</groupId>              <artifactId>springfox-swagger2</artifactId>              <version>2.2.2</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() {          ApiInfo apiInfo = new ApiInfo("Electronic Health Record(EHR) Platform API",//大标题                  "EHR Platform's REST API, all the applications could access the Object model data via JSON.",//小标题                  "0.1",//版本                  "NO terms of service",                  "365384722@qq.com",//作者                  "The Apache License, Version 2.0",//链接显示文字                  "http://www.apache.org/licenses/LICENSE-2.0.html"//网站链接          );            return apiInfo;      }        private ApiInfo demoApiInfo() {          ApiInfo apiInfo = new ApiInfo("Electronic Health Record(EHR) Platform API",//大标题                  "EHR Platform's REST API, for system administrator",//小标题                  "1.0",//版本                  "NO terms of service",                  "365384722@qq.com",//作者                  "The Apache License, Version 2.0",//链接显示文字                  "http://www.apache.org/licenses/LICENSE-2.0.html"//网站链接          );            return apiInfo;      }  }

经过这2步配置后,我们启动服务后,访问: http://localhost:8080/swagger-ui.html 就完成了集成。

下面创建2个Controller来测试:1、TestController.java

@Controller  @RequestMapping("/api/test")  public class TestController {        @ResponseBody      @RequestMapping(value = "/show", method=RequestMethod.POST)// 这里指定RequestMethod,如果不指定Swagger会把所有RequestMethod都输出,在实际应用中,具体指定请求类型也使接口更为严谨。      @ApiOperation(value="测试接口", notes="测试接口详细描述")      public String show(              @ApiParam(required=true, name="name", value="姓名")              @RequestParam(name = "name") 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 的后期版本应该会支持更全面的应用需求的。