springboot+swagger2说明

Posted stubbornness1219

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了springboot+swagger2说明相关的知识,希望对你有一定的参考价值。

swagger用于定义API文档。

优势:

  • 前后端分离开发
  • API文档非常明确
  • 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
  • 传统的输入URL的测试方式对于post请求的传参比较麻烦(当然,可以使用postman这样的浏览器插件
添加pom依赖
<!--swagger2 start-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>
<!--swagger2 end-->
Swagger2Config初始化配置如下: [java] view plain copy
  1. package com.gasq.travel.config;  
  2.   
  3. import com.gasq.travel.common.CodeEnum;  
  4. import com.gasq.travel.utils.collections.ListUtils;  
  5. import io.swagger.annotations.ApiOperation;  
  6. import org.springframework.beans.factory.annotation.Value;  
  7. import org.springframework.boot.context.properties.ConfigurationProperties;  
  8. import org.springframework.context.annotation.Bean;  
  9. import org.springframework.context.annotation.Configuration;  
  10. import org.springframework.web.bind.annotation.RequestMethod;  
  11. import org.springframework.web.context.request.async.DeferredResult;  
  12. import springfox.documentation.builders.ApiInfoBuilder;  
  13. import springfox.documentation.builders.PathSelectors;  
  14. import springfox.documentation.builders.RequestHandlerSelectors;  
  15. import springfox.documentation.builders.ResponseMessageBuilder;  
  16. import springfox.documentation.schema.ModelRef;  
  17. import springfox.documentation.service.ApiInfo;  
  18. import springfox.documentation.service.ResponseMessage;  
  19. import springfox.documentation.spi.DocumentationType;  
  20. import springfox.documentation.spring.web.plugins.Docket;  
  21. import springfox.documentation.swagger2.annotations.EnableSwagger2;  
  22.   
  23. import java.util.List;  
  24.   
  25. /** 
  26.  * @description: swagger2配置文件类 
  27.  * @访问路径: 如 http://localhost:8080/swagger-ui.html 
  28.  * @author fanpeng 
  29.  * @create 2017-01-03 10:00 
  30.  * @Modify By: 
  31.  **/  
  32. @Configuration  
  33. @EnableSwagger2  
  34. @ConfigurationProperties  
  35. public class Swagger2Config   
  36.     @Value("$swagger.version"private String version;  
  37.     @Value("$swagger.basePackage"private String basePackage;  
  38.   
  39.     @Bean  
  40.     public Docket createRestApi()   
  41.         return new Docket(DocumentationType.SWAGGER_2)  
  42.                 .apiInfo(apiInfo())  
  43.                 .groupName("travel")  
  44.                 .genericModelSubstitutes(DeferredResult.class)  
  45.                 .useDefaultResponseMessages(false)  
  46.                 .globalResponseMessage(RequestMethod.GET,customerResponseMessage())  
  47.                 .forCodeGeneration(true)  
  48.                 .select()  
  49.                 .apis(RequestHandlerSelectors.basePackage(basePackage))  
  50.                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  
  51.                 .paths(PathSelectors.any())  
  52.                 .build();  
  53.       
  54.   
  55.     private ApiInfo apiInfo()   
  56.         return new ApiInfoBuilder()  
  57.                 .title("国安社区-travel接口")  
  58.                 .description("I'm description..")  
  59.                 .contact("东哥")  
  60.                 .version(version)  
  61.                 .license("国安社区")  
  62.                 .licenseUrl("baidu.com")  
  63.                 .build();  
  64.       
  65.   
  66.     /** 
  67.      * 自定义返回信息 
  68.      * @param 
  69.      * @return 
  70.      */  
  71.     private List<ResponseMessage> customerResponseMessage()  
  72.         return ListUtils.convertToList(  
  73.                 new ResponseMessageBuilder()//500  
  74.                         .code(CodeEnum.error.getValue())  
  75.                         .message(CodeEnum.error.getDescription())  
  76.                         .responseModel(new ModelRef("Error"))  
  77.                         .build(),  
  78.                 new ResponseMessageBuilder()//401  
  79.                         .code(CodeEnum.paramError.getValue())  
  80.                         .message(CodeEnum.paramError.getDescription())  
  81.                         .build());  
  82.       
  83.   
  84.   
  85.   


Controller中测试方法:
在这里我们使用@ApiOperation注解来声明此方法为要生成的接口文档,在配置中已经配置过了,如果不想方法生成文档,不加此注解即可; 配置中已经使用了自定义的响应信息,所以可以不设置@ApiResponses;
[java] view plain copy
  1.     @ApiOperation(value="测试日志程序", notes="测试日志程序", produces = "application/json")  
  2.     @ApiImplicitParams(value =   
  3.             @ApiImplicitParam(name = "school", value = "学校名称", required = true, paramType = "query", dataType = "String"),  
  4.             @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query", dataType = "String")  
  5.     )  
  6.     @RequestMapping(value = "/get",method = RequestMethod.GET)  
  7.     public void testProgram(HttpServletRequest request, HttpServletResponse response)  
  8.         logger.debug("debug");  
  9.         logger.info("info");  
  10.         logger.error("error");  
  11.         logger.warn("warn");  
  12.   
  13.         Student student = studentCommandService.selectById(1);  
  14. //        Student student = studentCommandService.queryById(1l);  
  15.         System.out.println(student.toString());  
  16.         this.renderJson(CodeEnum.success.getValue(),CodeEnum.success.getDescription(),student,request,response);  
  17.       

注解说明:

  • @Api:用在类上,说明该类的作用
  • @ApiOperation:用在方法上,说明方法的作用
  • @ApiImplicitParams:用在方法上包含一组参数说明
  • @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
    • paramType:参数放在哪个地方
      • header-->请求参数的获取:@RequestHeader
      • query-->请求参数的获取:@RequestParam
      • path(用于restful接口)-->请求参数的获取:@PathVariable
      • body(不常用)
      • form(不常用)
    • name:参数名
    • dataType:参数类型
    • required:参数是否必须传
    • value:参数的意思
    • defaultValue:参数的默认值
  • @ApiResponses:用于表示一组响应
  • @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
    • code:数字,例如400
    • message:信息,例如"请求参数没填好"
    • response:抛出异常的类
  • @ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
    • @ApiModelProperty:描述一个model的属性
以上这些就是最常用的几个注解了。

需要注意的是:

  • ApiImplicitParam这个注解不只是注解,还会影响运行期的程序,例子如下:

  

如果ApiImplicitParam中的phone的paramType是query的话,是无法注入到rest路径中的,而且如果是path的话,是不需要配置ApiImplicitParam的,即使配置了,其中的value="手机号"也不会在swagger-ui展示出来。

 

具体其他的注解,查看:

https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

生成文档效果: 方法效果:

完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html,就能看到上文所展示的RESTful API的页面。

以上是关于springboot+swagger2说明的主要内容,如果未能解决你的问题,请参考以下文章

SpringBoot框架 之 Swagger2

SpringBoot集成Swagger2在线文档

SpringBoot整合Swagger2框架

基于Maven的Springboot+Mybatis+Druid+Swagger2+mybatis-generator框架环境搭建

SpringBoot2.0系列教程Springboot框架添加Swagger2来在线自动生成接口的文档+测试功能

SpringBoot Swagger2 可视化API