springBoot（15）：集成Swagger

一、简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。http://swagger.io/ 

Springfox 的前身是swagger-springmvc，是一个开源的API doc框架，可以将我们的 Controller的方法以文档的形式展现，基于Swagger。http://springfox.github.io/springfox/ 

二、操作

2.1、添加依赖

1 2 3 4 5 6 7 8 9 10 11

<!-- Swagger --> < dependency >     < groupId >io.springfox</ groupId >     < artifactId >springfox-swagger-ui</ artifactId >     < version >2.6.0</ version > </ dependency > < dependency >     < groupId >io.springfox</ groupId >     < artifactId >springfox-swagger2</ artifactId >     < version >2.6.0</ version > </ dependency >

2.2、代码

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43

package  com.example.demo.utils.configuration;   import  static  springfox.documentation.builders.PathSelectors.regex; import  org.springframework.context.annotation.Bean; import  org.springframework.context.annotation.Configuration; import  springfox.documentation.builders.ApiInfoBuilder; import  springfox.documentation.builders.RequestHandlerSelectors; import  springfox.documentation.service.ApiInfo; import  springfox.documentation.service.Contact; import  springfox.documentation.spi.DocumentationType; import  springfox.documentation.spring.web.plugins.Docket; import  springfox.documentation.swagger2.annotations.EnableSwagger2;   /**   * Swagger配置   * @Author: 我爱大金子   * @Description: Swagger配置   * @Date: Create in 11:33 2017/6/22   */ @Configuration @EnableSwagger2 public  class  Swagger2Configuration {      @Bean      public  Docket accessToken() {          return  new  Docket(DocumentationType.SWAGGER_2).groupName( "index" ) // 定义组                  .select()  // 选择那些路径和 api 会生成 document                  .apis(RequestHandlerSelectors.basePackage( "com.example.demo.controller" ))  // 拦截的包路径                  .paths(regex( "/index/.*" )) // 拦截的接口路径                  .build()  // 创建                  .apiInfo(apiInfo());  // 配置说明      }      private  ApiInfo apiInfo() {          return  new  ApiInfoBuilder() //                  .title( "测试" ) // 标题                  .description( "spring boot 全集" ) // 描述                  .termsOfServiceUrl( "http://www.roncoo.com" )//                  .contact( new  Contact( "我爱大金子" ,  "http://1754966750.blog.51cto.com/" ,  "a1754966750@qq.com" ))// 联系                  // .license("Apache License Version 2.0")// 开源协议                  // .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")// 地址                  .version( "1.0" ) // 版本                  .build();      } }

测试用的Controller:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

@RestController @RequestMapping ( "/index" ) public  class  IndexController {      @Autowired      private  UserMapper mapper;        @RequestMapping (value =  "/index" , method = RequestMethod.POST)      public  Map<String, Object> index(Integer id)  throws  Exception {          Map<String, Object> map =  new  HashMap<String, Object>();          User user = mapper.selectByPrimaryKey(id);          if  ( null  != user) {              map.put( "id" , user.getId());              map.put( "name" , user.getName());          }  else  {              map.put( "id" , - 1 );              map.put( "name" ,  "error" );          }          return  map;      } }

效果：访问http://localhost:8989/swagger-ui.html 

2.3、自定义(注解的使用)

@ApiIgnore

 忽略暴露的 api

@ApiOperation(value = "查找", notes = "根据用户 ID 查找用户")

 添加说明

其他注解：

@Api ：用在类上，说明该类的作用

@ApiImplicitParams ：用在方法上包含一组参数说明

@ApiResponses ：用于表示一组响应

@ApiResponse ：用在@ApiResponses 中，一般用于表达一个错误的响应信息

 code：数字，例如 400

 message：信息，例如"请求参数没填好"

 response：抛出异常的类

@ApiModel ：描述一个 Model 的信息（这种一般用在 post 创建的时候，使用@RequestBody 这样的场景，请求参数无法使用@ApiImplicitParam 注解进行描述的时候）

@ApiModelProperty ：描述一个 model 的属性

更多请查看：https://github.com/swagger-api/swagger-core/wiki/Annotations 

本文转自我爱大金子博客51CTO博客，原文链接http://blog.51cto.com/1754966750/1940912如需转载请自行联系原作者

我爱大金子