Java后端程序员java学习

使用spring-boot-starter-swagger实现A

2018-02-07  本文已影响1386人  扁圆柱体

为什么要实现API文档化？

  1. API文档化有利于前后端分离的开展。随着开发方式全面转成前后端分离，前端和后端的唯一沟通就在API层面。在没有文档化之前，开发人员只能口头的交代并反复理解每个接口参数和返回值，这个过程相当不稳定，变化频繁。而通过API文档化后，可以通过文档的清晰定义，使得前后端人员减少无畏沟通，并在理解上保持一致；

  2. API文档化有利于接口自动化测试。公司马上上马接口自动化测试，对接口参数和返回值要通过Json方式导入自动化测试程序。而用特殊工具生成的API文档，可以直接输出json格式的文档，简化了测试流程，减轻了开发人员的工作量；

  3. API文档化有利于系统文档建设。开发人员不愿意写文档，写注释。而为了以上两个目的必须要求开发人员在编码的同时补充相关的API描述，而通过一个相对稳定成熟和趁手的工具可以大大减轻文档的工作量，做到事半功倍。

Swagger和spring-boot-starter-swagger

Swagger是业界比较流行的实现API文档化的工具。优点有

  1. 通过在项目中引入Swagger，可以使用简单的Annotation，就实现了API文档化；
  2. Swagger提供标准的json或yaml文档，方便做进一步解析，典型应用是接口自动化测试；
  3. 页面可以直接进行测试（try-it-out功能，部分替代Postman）；
  4. Swagger还提供类似于github的SwaggerHub，相当于公共的API文档集散地。

Swagger的项目主页：https://swagger.io/

为了将Swagger和公司现有技术框架相结合，在网上发现了这么一个小项目spring-boot-starter-swagger，将公司项目和Swagger的集成又简化了一步，特此向作者表示感谢。
作者在简书上的介绍文章：https://www.jianshu.com/p/91c5a8565a45

主要优点：

  1. 引入足够简单，只需要2步（如果有Shiro就是3步）
  2. 方便的Swagger开关
  3. 支持yaml格式的配置
  4. 支持API的分组显示（在API过多的情况下非常好用）
  5. 支持JSR-303校验注解（@Min, @Max, @Pattern等）
  6. 依然在维护完善，逐步增加更多配置和开关

Swagger引入方法

  1. pom文件引入
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>spring-boot-starter-swagger</artifactId>
            <version>1.5.1.RELEASE</version>
        </dependency>
  1. 主文件加Annotation
@SpringBootApplication
@EnableSwagger2Doc
public calss TestSwaggerApplication{
  1. 增加Shiro的anon设置（防止被登录转向）
client:
  filters:
  filter:
    chain:
      definitions: /swagger-ui.html=anon;/webjars/**=anon;/swagger-resources/**=anon;/v2/api-docs/**=anon;/**=authc;
  1. 配置文件
    配置文件统一放到了项目的application.yml中，稍后计划使用新的文件，并采用引入的方式实现配置文件的分离

4.1 公共信息
定义整个项目的总体信息。

swagger:
  # 公共信息
  enabled: true
  title: swagger-demo
  description: 一个Swagger测试项目
  version: 0.1-SNAPSHOT
  # 许可证及服务条款信息
  license:
  licenseUrl:
  termsOfServiceUrl:
  contact:
    name: Carisma
    url:
    email: carisma.zhao@gmail.com
  base-package: me.learning.swagger

4.2 分组策略
分组策略指的是在整个项目中，将不同类型的API接口分散到不同的页面，方便查看和测试。

# 分组策略
  docket:
    apiForMe:
      title: Myself
      description: 开放给自己的接口
      base-path: /api/myself/**
    apiForOthers:
      title: Others
      description: 作为其他人的接口
      base-path: /api/others/**

4.3 公共参数和通用错误码
像每个接口都需要鉴权这种参数，可以在配置文件中统一定义，这样省去每个接口再写的麻烦，也能兼顾页面的测试。

# 公共参数
  global-operation-parameters[0]:
    name: TOKEN
    description: 鉴权
    modelRef: string
    parameterType: header
    # 公共参数写成requierd, 对于不需要登录的接口随便写一个字符串即可
    required: true
  # 通用返回错误码
  apply-default-response-messages: true
  global-response-message.get[0]:
    code: 401
    message: 401错误
  global-response-message.get[1]:
    code: 500
    message: 后端错误
    modelRef: ERROR

Swagger的效果查看

以上配置完成后，Swagger直接可以生成文档，而不需要单独在每个需要显示的API上添加Annotation，当然下面会讲到如果需要更清晰的显示，还要使用注解，使用注解后，查看方式依然是以下两种。

  1. API文档：在浏览器中输入localhost:9120/swagger-ui.html即可。端口号为Application的启动端口；
  2. Json文件：如果没有分组，则直接使用localhost:9120/swagger-ui.html/v2/api-doc，即显示API的Json格式（包括对model的解析），如果使用了分组，则需要每个分组单独显示，例如localhost:9120/swagger-ui.html/v2/api-doc/?group=apiForMe

Annotation使用详解

要想详细的、切合实际的展示API的内容与要求，则必须在API和Model上加单独的注解，官方JavaDoc虽然不是很详细，但是作为参考也够了（剩下的就是自己试了）：
http://docs.swagger.io/swagger-core/current/apidocs/index.html?io/swagger/annotations/Api.html

其中常用的有以下几个，亲测后有些需要详细说明：

@Api
加在需要自定义注解的API类（*Controller）上。这个注解没有什么属性需要说的，其中value比较奇葩，官方说法是隐含的代替tag的作用。（那就用tag不就完了？）为了清晰化接口，使用方式应该是分组>tag>value，即首先用分组分隔，然后使用tag属性，value属性最好就不再使用了。

@ApiOperation
加在API的每个路径映射方法上（即真正的API接口）。value属性是必须的，描述该接口的内容，可以是中文。
response和responseContainer是两个重要的属性。前者表示返回的类，典型的Model.class，注意不是字符串，IDEA是可以解析的（Swagger体系内自动的做成一种Reference）；后者可选值为："List"，"Set"或者"Map"，注意是字符串。

@ApiImplicitParam & @ApiImplicitParams
加在API的参数上，最重要的注解之一。另有一个@ApiParam，是加在函数签名里面，不推荐，这两个是在函数签名的外面，更清晰。后者是前者的集合，比较简单，就不赘述了。前者比较重要的属性有

  1. name：和参数变量名保持一致；
  2. value：对这个参数的简要描述；
  3. required：是否必须；
  4. dataType：数据类型，注意原生类型（包装类也用原生的表示，例如Integer写"int"）都是小写，包括"string"；
  5. paramType：参数类型，"body"是普通参数，"path"是路径上的那种参数，"query"是url中问号的那种参数；
  6. allowableValues：参数允许的值，这个属性对自动化测试比较重要，具体参考JavaDoc，实际使用中最好写明。需要说明的是，在paramType为body时，range的设置是不生效的（原因未知）。

@ApiModel
以下两个注解都是加在Model里，便于在文档中对自定义类做详细的说明。这个注解加在Model类上。value属性可以提供一个名字，在文档中，会替换原来model的类名（没有试中文是否可行）。同时提供对超类和子类的描述，非字符串，便于生成继承关系（感觉这个功能可以通过代码分析实现）

@ApiModelProperty
加在Model的属性上，对属性做进一步描述和限定。同时这个注解可以加在getXXX方法上，如果XXX属性上也有，则以属性上的注解描述为准。考虑提供方法上加注解，可能是方便描述超类中的这个字段吧（protected类型）。该注解使用方式和@ApiImplicitParam类似。
由于引入了spring-boot-starter-swagger，可以直接支持JSR-303校验类的注解，包括@Pattern、@Max、@Min、@Size等。感觉Pattern是无法用@ApiModelProperty的属性替代的，其他好像都可以，说的不对还请作者指正。

上一篇下一篇

猜你喜欢

热点阅读