Swagger & SpringBoot

API 文档框架

此文章基于 swagger 2.0+,不包含 3.0 新特性

前言

现在企业普遍都是前后端分离进行项目开发,也就是:由前端渲染页面、后端提供接口。前端和后端的的联系变得微弱,而让前端与后端和谐开发的必备因素之一就是:接口文档

手写 API 文档的痛点:

  • 文档更新不及时
  • 接口返回结果不明确
  • 不能直接在线测试接口
  • 难以维护
  • ...

Swagger 的出现为我们提供了一套通过代码和注解自动生成文档、在线测试文档的方法,这一点对于保证 API 文档的及时性、易用性将有很大的帮助

RESTful 相关知识可参考:https://github.com/aisuhua/restful-api-design-references

特性

  1. 只需要少量的注解,Swagger 就可以根据代码自动生成 API 文档,很好的保证了文档的时效性。
  2. 跨语言性,支持 40 多种语言。
  3. Swagger UI 呈现出来的是一份可交互式的 API 文档,我们可以直接在文档页面尝试 API 的调用,省去了准备复杂的调用参数的过程。
  4. 导入相关的工具(例如 SoapUI), 这些工具将会为我们自动地创建自动化测试。
  5. ...

如何集成

  • Maven 依赖
<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger2.version}</version>
</dependency>
<!--swagger ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger2.version}</version>
</dependency>
  • 开启 swagger
@Configuration
// 启用 Swagger2
@EnableSwagger2
public class SwaggerConfig {
    public SwaggerConfig() {
    }

    @Bean
    public Docket createRestApi() {
        ParameterBuilder tokenBuilder = new ParameterBuilder();
        List<Parameter> parameterList = new ArrayList();
        tokenBuilder.name("Authorization").defaultValue("去其他请求中获取heard中token参数").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(true).build();
        parameterList.add(tokenBuilder.build());
        return (new Docket(DocumentationType.SWAGGER_2))
        // 文档信息对象
        .apiInfo(this.apiInfo())
        .select()
        // 被注解的包路径
        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        .paths(PathSelectors.any())
        .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
          // 标题
          .title("swagger API")
          // 描述
          .description("这里是 RESTful API 描述")
          .termsOfServiceUrl("https://fuoshuo.com")
          // 文档作者信息
          .contact(new Contact("", "", ""))
          .license("")
          .licenseUrl("")
          // 文档版本
          .version("1.0.1")
          .build();
    }
}
  • 现在即可通过地址访问你的 swagger 文档了http://ip:port/swagger-ui.html

常用注解

想生成的 swagger 文档丰富、接口参数不丢失、前端不会提刀来见,还得运用好以下几个注解才行:

Swagger的所有注解定义在io.swagger.annotations包下,此处并不包含全部

Controller 相关注解

  • @Api:作用于类上
注解属性类型描述
tagsString[]控制器标签(大标题)
value
descriptionString控制器描述(小标题,已被标为过期)
  • @ApiOperation:作用于具体方法上
注解属性类型描述
valueString接口标题
notesString接口发布说明
tags[]String分类标签
responseClass<?>接口返回类型
  • @ApiIgnore: 作用于具体方法上,Swagger 文档不会显示拥有该注解的接口(接口过滤还可以在 Docket上增加筛选)
  • @ApiImplicitParams: 作用于具体方法上,用于描述接口的非对象参数集,一般与@ApiImplicitParam组合使用
  • @ApiImplicitParam: 作用于具体方法上,用于描述接口的非对象参数
  • @ApiParam:作用于具体参数上,用于单个参数描述
以下参数同时适用于 @ApiImplicitParam 与 @ApiParam
注解属性类型描述
nameString参数名称(英文)
valueString参数描述(中文)
requiredboolean是否必填,默认 false
dataTypeString参数数据类型
paramTypeString参数取值位置
参数取值位置:如path、body、query、header。此注解会直接影响接口的测试 header 对应注解:@RequestHeader query 对应注解:@RequestParam path 对应注解: @PathVariable body 对应注解: @RequestBody

Model 相关注解

  • ApiModel:作用于实体类上
注解属性类型描述
valueString对象名称
descriptionString对象描述
  • ApiModelProperty:作用于实体类属性上
注解属性类型描述
valueString字段说明
exampleStirng举例说明
hiddenboolean是否在文档中隐藏该字段
allowEmptyValueboolean是否允许为空
allowableValuesString该字段允许的值,当我们 API 的某个参数为枚举类型时,使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值

最后

无论是出于安全考虑还是节约内存等角度,正式环境一定要记得关闭 Swagger。

参考


添加新评论

还没有评论哟 ~