接口规范说明（apifox）

API 文档层级概念

四层目录的示例图，展示逻辑项目名称、领域模块、功能模块和接口列表的层级结构：

逻辑项目名称
├── 领域模块1
│   ├── 功能模块1
│   │   ├── 接口1
│   │   ├── 接口2
│   │   └── 接口3
│   └── 功能模块2
│       ├── 接口4
│       ├── 接口5
│       └── 接口6
└── 领域模块3
    ├── 功能模块5
    │   ├── 接口13
    │   ├── 接口14
    │   └── 接口15
    └── 功能模块6
        ├── 接口16
        ├── 接口17
        └── 接口18

例如，如果逻辑项目是 【三方订单系统】，目录结构可以具体化为：

三方订单系统（一级）
├── 需求单管理（二级）
│   ├── PC-需求单创建（三级）
│   │   ├── 创建订单接口
│   │   ├── 收件人查询接口
│   │   └── 收件人添加接口
│   └── APP-需求单创建
│       ├── 创建订单接口
│       ├── 收件人添加接口
│       └── 寄件人查询接口
└── 三方包裹管理
    ├── APP-包裹交接接口
    │   ├── 包裹详情查询接口
    │   ├── 包裹交接确认接口
    │   └── 包裹交接列表查询接口
    └── APP-包裹打印接口
        ├── 打印信息查询接口
        └── 打印状态更新接口

swagger 使用强制规范

 

@Api主键中 value 值为 【功能模块】， tags值为【领域模块】，且只能写一个 tag。示例：

@Api(value = "APP-需求单管理", tags = ApiTag.MODULE_DEMAND_ORDER)
// 目录指向 ->  项目名称/{MODULE_DEMAND_ORDER}/APP-需求单管理

 

@ApiOperation 接口定义，value为接口的名称， tags可以打标，可以记录多个标记，可用于快速查询和定位

@ApiOperation(value = "需求单列表分页查询", tags = {ApiTag.APP, ApiTag.QUERY})

最佳实战

 

邀请地址：接口平台 https://app.apifox.com/invite?token=9jbKoM7QVwnRFR5knuywV

 

【约束】昵称请使用真实姓名，更好管理和跟踪

创建项目

创建一级目录【逻辑项目级】

 

创建的逻辑：按面向前端的接口服务维度创建

 

同时创建前缀域名，在环境变量中配置

为一级目录选择 服务前缀

 

📣注意：如果一级目录 是几个服务的聚合，那么需要在具体的目录层级设置前缀

接口上传

规则配置

 

IDEA 下载插件，配置相关规则

配置示例：

 

规则配置

这里配置可以添加到自己idea配置中

#configs
#dev=false
#auto.format.url=true
#max.deep=10
#max.elements=512
folder.name=#folder
# ApiParam
param.doc=@io.swagger.annotations.ApiParam#value
param.default.value=@io.swagger.annotations.ApiParam#defaultValue
param.required=@io.swagger.annotations.ApiParam#required
param.ignore=@io.swagger.annotations.ApiParam#hidden

# Api
#class.doc=@io.swagger.annotations.Api#value
module=@io.swagger.annotations.Api#tags
ignore=@io.swagger.annotations.Api#hidden

# ApiModel
class.doc=@io.swagger.annotations.ApiModel#value
class.doc=@io.swagger.annotations.ApiModel#description

# ApiModelProperty
json.rule.field.name=@io.swagger.annotations.ApiModelProperty#name
field.ignore=@io.swagger.annotations.ApiModelProperty#hidden
field.doc=@io.swagger.annotations.ApiModelProperty#value
field.schema.title=@io.swagger.annotations.ApiModelProperty#value
field.doc=@io.swagger.annotations.ApiModelProperty#notes
field.required=@io.swagger.annotations.ApiModelProperty#required

# ApiOperation
method.doc=@io.swagger.annotations.ApiOperation#value
api.tag=@io.swagger.annotations.ApiOperation#tags

映射关系

 

swagger标记

上传接口

 

右键选择上传，选择 tag 级别的二级目录，如果没有可以右键创建一个二级目录

 

二级目录是领域模块

 

📣注意：只有当前模块首次上传才会有弹窗，如果选择过，则同一个 tag 的会自动上传，如果要清除配置，则再设置插件里面去除即可

目录进阶使用

 

如果在项目中某些接口特殊要放入其他目录

 

如：下面这个接口上传的路径： 一级目录/三方包裹管理/APP-三方包裹/GET 查询包裹列表

 

假设我们想将这个接口上传到： 一级目录/三方包裹管理/APP-三方包裹/**查询**/GET 查询包裹列表

 

此时我们可以在接口的注释中添加 @folder APP-三方包裹/查询；

 

类层级上的 @Api注解的 value 也是支持路径格式来编写， 像下面的编写则代表当前类的接口全部会放在 **APP-三方包裹/包裹交接**目录下

@Api(value = "APP-三方包裹/包裹交接", tags = "三方包裹管理")