Swagger环境搭建

什么是Swagger？
Swagger是一款RESTFUL接口的文档在线自动生成+功能测试工具，专门用于生成/描述/调用和可视化RESTFUL风格的Web服务

一.依赖引入与环境构建

1.引入依赖

• 引入springfox-swagger2依赖

  compile group: 'io.springfox',  name: 'springfox-swagger2', version: '2.9.2'
  

• 注意：通常情况下，我们可以通过直接引入springfox-swagger-ui，通过自动生成的/webjar/下的swagger-html文档内容可以直接查看，但文档的访问地址只能是http://localhost:8080/swagger-ui.html。而由于项目是前后端分离的，我们通过loadbalancer的listener rule和cloudfront的behavior会配置指定如/swagger开头的链接打到后端，其他的请求打到前端，且由于多个微服务需要进行接口的区分，我们更多会希望修改swagger的展示地址，如http://localhost:8080/swagger/api/doc/index.html
• 基于上述原因，我们可以不通过引入springfox-swagger-ui依赖自动生成，而采用swagger-ui源码的方式直接使用模板，操作步骤如下
  • clone https://github.com/swagger-api/swagger-ui 项目
  • 将项目中的dist文件夹拷贝到resource/swagger目录下
  • 在application.properties中定义springfox.documentation.swagger.v2.path=/swagger/api/doc将源/v2/api-docs json文档地址调整为/swagger/api/doc（修改api docs json数据的请求路径,swagger-ui是通过获取接口的json数据渲染页面的）
  • 修改resource/swagger/dist下的index.html文件，将其中的url = "http://petstore.swagger.io/v2/swagger.json"修改为url = “/swagger/api/doc”

2.环境构建

• 在Springboot Application启动文件中配置Swagger插件信息（注：此处想配置更多内容，请参阅springfox官方文档）

  /**
   * 注册Swagger配置
   */
  @Bean
  public Docket swaggerSpringRegister() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
                  .apis("")//定义要引入的API包
                  .paths(Predicates.not(PathSelectors.regex("/error.*")))//定义要匹配的路径
                  .build()//
              .useDefaultResponseMessages(false)//设置文档是否采用默认的http响应内容
              .apiInfo(apiInfo())//定义文档的内容
              .securitySchemes(securitySchemes())//定义security schemes用于保护API
              .securityContexts(securityContexts());//定义要保护的上下文API和对应的scheme关系
              //默认请求都是以/根路径开始,如果我们的应用不是部署在根路径,比如以/test部署,则可以通过.pathMapping("/platform")的方式设置请求的统一前缀
  }
  
  /**
   * 定义文档内容
   */
  private ApiInfo apiInfo() {
      return new ApiInfoBuilder()
              .title("Test document")
              .description("Document sample description")
              .build();
  }
  
  private List<ApiKey> securitySchemes() {
      return newArrayList(new ApiKey("Authorization", "Authorization", "header"));
  }
  
  private List<SecurityContext> securityContexts() {
      return newArrayList(
              SecurityContext.builder()
                      .securityReferences(defaultAuth())
                      .forPaths("^(?!auth).*$")
                      .build()
      );
  }
  
  List<SecurityReference> defaultAuth() {
      AuthorizationScope authorizationScope = new AuthorizationScope("global","access");
      AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
      authorizationScopes[0] = authorizationScope;
      return newArrayList(new SecurityReference("authorization"));//定义指定scheme的作用范围
  }
  

• 增加url映射，使得访问对应API的时候可以转到静态资源

    @configuration
    @SpringBootApplication
    public class DemoApplication extends WebMvcConfigurerAdapter {
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/rest/api/doc/**").addResourceLocations("classpath:/swagger/dist/");
        }
    }
  

• 此时，访问http://localhost:8080/swagger/api/doc/index.html即可以看到对应的swagger文档；也可以通过访问http://localhost:8080/swagger/api/doc/ 的形式直接查看json格式的文档内容

二.常用的Swagger注释API说明

1.针对于API

• @Api：作用在Controller类上，定义描述当前Controller
• @ApiOperation：作用在controller的方法上
• @ApiResponses：作用在controller的方法上
• @ApiResponse：作用在@ApiResponses里面
• @ApiImplicitParams：作用在controller的方法上
• @ApiImplicitParam：作用在@ApiImplicitParams的方法里边

属性	取值	作用
paramType		参数类型
	path	url参数信息@PathVariable
	query	请求参数@RequestParam
	body	请求体@RequestBody
	header	请求头中参数
	form	以表单形式提交
dataType		参数的数据类型，只作为标志说明，没有实际验证
	Long
	String
name		接收的参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值
example		样例值

• @ApiParam：作用在方法参数上
• ApiImplicitParam 与 ApiParam 的区别
  • 对Servlets或者非 JAX-RS的环境，只能使用 ApiImplicitParam。
  • 在使用上，ApiImplicitParam比ApiParam具有更少的代码侵入性，只要写在方法上就可以了，但是需要提供具体的属性才能配合swagger ui解析使用。
  • ApiParam只需要较少的属性，与swagger ui配合更好。
• 示例代码

    @ApiOperation("定义方法描述")
    @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"),
            @ApiResponse(code = CommonStatus.EXCEPTION, message = "服务器内部异常"),
            @ApiResponse(code = CommonStatus.FORBIDDEN, message = "权限不足") })
    @ApiImplicitParams({ 
        @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "信息id", required = true),
        @ApiImplicitParam(paramType = "path", dataType = "Long", name = "userId", value = "用户Id", required = true),
        @ApiImplicitParam(paramType = "header", dataType = "String", name = "Content-type", value = "类型", required = true)
        })
    @RequestMapping(value = "/test/{userId}", method = RequestMethod.GET, produces = "application/json")
    public RestfulProtocol test(Long id,@PathVariable("userId") Long userId) {}
    //其中produces表示的是以什么格式传递数据
  

2.针对于Model

• @ApiModel：作用在返回对象类上，用于描述类
• @ApiModelProperty：作用在对象的属性上，用于描述属性含义
• 示例代码

  @ApiModel("测试类")
  class test {
      @ApiModelProperty(value="标题")
      private String title;
  }
  

三.爬坑记录

• 问题:给API的Long型参数添加@ApiParam()或@ApiImplicitParam()时,控制台报错java.lang.NumberFormatException: For input string: “”
  • 由于有个默认值是空字符串的变量转换成Integer类型时异常，需要给注解添加example属性，且值是可以转换成Long的
  • 修改前的代码

  @ApiImplicitParam(paramType = "path", dataType = "Long", name = "demoId", value = "demo id", required = true)
  

  • 修改后的代码

  @ApiImplicitParam(paramType = "path", dataType = "Long", name = "demoId", value = "demo id", required = true, example = "123")
  

  • 注意：example定义的内容一定要可以转成对应的参数类型

四.总结

• Swagger其实就是生成文档和API简单接口测试的工具，再多的配置也都是将文档描述的更加完备，建议还是需要的时候查看文档进行配置即可。