接口文档管理《十六》_大公司接网站的接口文档-CSDN博客

本文链接：https://blog.csdn.net/qq_35781178/article/details/81784013

分布式架构中的各个服务最终产出restful 风格的API接口，提供给前端（ios,android,web）或其他第三方程调用，一份丰富完整的接口描述文档能够大大降低沟通成本。

swagger 由两部分组成：

swagger-codegen:生成json 格式的接口描述文档。

swagger-ui : 提供界面解析接口描述文档。

swagger官网：https://swagger.io/

Dubbo 中使用swagger2:

swagger 主要在controller中描述接口信息，在Dubbo 架构中所有的服务都将由网关模块调用dubbo服务转为restful api，所以swagger 的整合也将在网关模块中进行。

Maven-model	用于解析maven的pom文件中的内容
`springfox-swagger2`	用于生成接口描述文档的核心依赖
`springfox-swagger-ui`	用于解析接口描述的界面依赖

`MavenXpp3Reader`	读取Maven的pom文件内容，并获取版本
Apiinfo	用于配置该应用所产生的接口基本描述信息
Docket	用于构建swagger接口描述文档，并通过api指定接口所在的位置

@Api	接口将以Controller进行分组，该注解用于描述该Controller信息
`@ApiOperation`	描述该接口的信息
Value	接口名称
Notes	接口详细描述
`@ApiImplicitParam`	描述该接口所接受的参数信息
Name	参数名称
Value	参数介绍
ParamType	参数接收类型
DefaultValue	Swagger ui 中显示的默认值
dataType	参数类型
`@ApiResponse`	描述该接口的返回内容
`Code`	http 返回状态
`Message`	状态描述
`Response`	返回值类型

描述实体参数与返回实体信息：通过实体接收参数以及接口内容通过实体序列化为json已经是常用方法。

value:参数名称

example:默认数据

required:请求时该参数是否为必须的。

spring cloud 中使用swagger2:

在dubbo 中所有的controller 都集中在网关模块中，而spring cloud 的各controller 分布在各微服务模块中，并由zuul 代理对外暴露。在配置swagger 也同样如此，每个微服务将产出各自的json 格式的API 文档，并在zuul 网关中通过swagger UI统一管理。

Swagger注解

注解	说明
`Api`	用在类上，说明该类的作用
`ApiModel`	描述一个 `Model` 的信息，使用 `@RequestBody` 的场景
`ApiModelProperty`	描述一个 `Model` 的属性
`ApiOperation`	用在方法上，说明方法的作用
`ApiParam`	请求属性
`ApiResponse`	用在 `@ApiResponses` 中，一般用于表达一个错误的响应配置
`ApiResponses`	用于表示一组响应集配置
`ResponseHeader`	响应头设置
`ApiImplicitParams`	用在方法上包含一组参数说明
`ApiImplicitParam`	用在 `@ApiImplicitParams` 注解中，指定一个请求参数的各个方面

Swagger注解属性

属性	说明
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象,默认响应类 Void
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的状态码默认 200
message	状态码对应的响应信息
extensions	扩展属性
name	属性名称
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
example	举例子
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
description	头描述
paramType	参数放在哪个地方
dataType	参数类型，有String/int，无用