为什么要写接口文档?
项目基于前后端分离, 而 接口文档 就是 统一定义前后端沟通开发的文档 。
接口文档 主要由后端Java开发工程师来写。
前端工程师:
把精力放在html,css,javaScript,vue,ajax,Google V8引擎,javascript多线程,模块化,面向切面编程,设计模式,浏览器兼容性,性能优化等等。
后端工程师(Java):
把精力放在设计模式,spring+springmvc,linux,mysql事务隔离与锁机制,mongodb,http/tcp,多线程,分布式架构,弹性计算架构,微服务架构,java性能优化,以及相关的项目管理等等。
接口文档的表现形式
接口文档的类型 | 主要功能 |
word文档、md文档、html文档 | 不推荐使用 |
yapi 接口文档 | |
Swagger 接口文档 | 在线自动生成 和 功能测试 |
knife4j 接口文档(Swagger的升级版) | 文档说明 和 在线调试 |
接口测试工具 | |
Postman 功能测试 | 功能测试 |
Swagger接口文档
官方文档:API Documentation & Design Tools for Teams | Swagger
Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger主要作用是:
使得前后端分离开发更加方便,有利于团队协作
接口的文档在线自动生成,降低后端开发人员编写接口文档的负担
功能测试:
Spring已经将Swagger纳入自身的标准,建立了Spring-swagger项目,现在叫Springfox。通过在项目中引入Springfox ,即可非常简单快捷的使用Swagger。
Swagger常用注解
@Api:修饰整个类,描述Controller的作用 @ApiOperation:修饰类的一个方法 标识 操作信息 接口的定义 @ApiParam:单个参数的描述信息 @ApiModel:描述使用到的对象信息 @ApiModelProperty:描述使用到的对象的属性信息 @ApiResponse:HTTP响应其中1个描述 @ApiResponses:HTTP响应整体描述 @ApiIgnore:使用该注解忽略这个API @ApiError :发生错误返回的信息 @ApiImplicitParam:一个请求参数 @ApiImplicitParams:多个请求参数的描述信息 @ApiImplicitParam属性 |
@ApiImplicitParam属性:
属性 | 取值 | 作用 |
---|---|---|
paramType | 查询参数类型 | |
path | 以地址的形式提交数据 | |
query | 直接跟参数完成自动映射赋值 | |
body | 以流的形式提交 仅支持POST | |
header | 参数在request headers 里边提交 | |
form | 以form表单的形式提交 仅支持POST | |
dataType | 参数的数据类型 只作为标志说明,并没有实际验证 | |
Long | ||
String | ||
name | 接收参数名 | |
value | 接收参数的意义描述 | |
required | 参数是否必填 | |
true | 必填 | |
false | 非必填 | |
defaultValue | 默认值 |
knife4j接口文档
官方文档:knife4j
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!
主要包括两大核心功能:文档说明 和 在线调试
1.文档说明:详细列出接口文档的说明
2.在线调试:在线功能测试
3.个性化配置:通过个性化ui配置项,可自定义UI的相关显示信息
4.离线文档:进行拷贝,可以使用第三方工具转换成html或pdf
5.接口排序:实现接口的排序
注解 | 说明 |
---|---|
@EnableSwagger2 | 该注解是Springfox-swagger框架提供的使用Swagger注解,该注解必须加 |
@EnableKnife4j | 该注解是knife4j 提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,如果你想使用这些增强功能就必须加该注解,否则可以不用加 |