首页 > 其他分享 >规范 - 接口文档

规范 - 接口文档

时间:2024-03-26 20:34:14浏览次数:21  
标签:xn 规范 接口 业务 描述符 文档 更新 使用

规范 - 接口文档

作者:Zonezzc
最后更新时间:2024-03-26 19:13:06


规范-接口文档

原则

  1. 接口的命名最终一定是便于理解的中文。
  2. 接口的说明中一定包含接口原名如 getSellerStandardsProfile,若存在第三方在线接口文档,该原名设置为引向原文的超链接。
  3. 所有的参数都要有中文注释。

命名规范

对接口理解不透彻时先使用接口的英文原文或接口的源代码名称占位,以防错误的理解翻译对他人造成理解困难。

例:

  • 广告 - 创建(批量ByInventoryReference)
  • 广告报表任务 - 生成 - 查询(生成状态)
  • 促销活动 - 查询
  • getSellerStandardsProfile

形如:x1 - ... - xn-1(xn)

  • -​ 符号前后各自有且仅有一个空格。
  • ()​ 为中文括号,且前后与内部皆无空格。
  • x1、xn-1、xn​ 在该规范中仅作为占位符存在,不表示长度限制。在保证语义的情况下尽可能简短,以便于检索。
  • 同一接口目录下的 x1​ 尽可能保持相同且唯一,用于表示父级层级,可与目录或目录含义保持相同。
  • xn​ 表示描述有 N 个层级,N 的值尽量不要大于 3。
  • xn-1​ 位置的描述符见下文。

xn-1​位置描述符规范

基础描述符

描述符 说明
创建 只执行创建或新增业务使用该描述符。
查询 查询或获取数据业务使用该描述符。
更新 只执行更新数据业务使用该描述符。
删除 只执行删除业务使用该描述符。

高级描述符

描述符 说明
保存 执行『创建』或『更新』 的业务使用该描述符。
克隆 基于已『创建』的内容部分『更新』生成相同本质的『创建』业务使用该描述符。
生成 基于已『创建』的内容产生新的不同本质的『创建』业务使用该描述符。

生命周期描述符

描述符 说明
启动 具有特殊生命周期业务的『更新』使用该描述符。
暂停 具有特殊生命周期业务的『更新』使用该描述符。
恢复 具有特殊生命周期业务的『更新』使用该描述符。
停止 具有特殊生命周期业务的『更新』使用该描述符。

资源描述符

描述符 说明
上传 需要资源上传的业务使用该描述符。
下载 需要资源下载的业务使用该描述符。

xn​位置描述符规范

描述符 说明
批量 该描述符仅存在于 xn​ 位置,用于表述接口中的 s​ 等复述形式(需要具有较多返回值,而非单个返回)。
目的/目标 用于表示目标或目的,例 xx - 查询(学生)​,xx - 查询(校区)​。
Byxxx/Forxxx/xxx 用于表示筛选条件时尽量不要出现中文,使用接口中的英文原文进行描述,注意英文的驼峰书写,且首字母大写。

标签:xn,规范,接口,业务,描述符,文档,更新,使用
From: https://www.cnblogs.com/zonezzc/p/18097504/specifications-interface-documentation-1jne2e

相关文章

  • 中国黄金集团携手e签宝,推动招投标电子化、规范化
    中国黄金集团有限公司组建于2003年初,其前身是成立于1979年的中国黄金总公司。是国内黄金行业唯一一家中央企业,集团主要从事金、银、铜、钼等有色金属的勘察设计、资源开发、产品生产和销售以及工程总承包等业务,是集地质勘探、矿山开采、选矿冶炼、产品精炼、加工销售、科研开发......
  • springboot整合knife4j接口文档
    1、添加knife4j依赖这里是最新版本的依赖,我也会使用这个最新版本的依赖来进行举例。knife4j官网<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-spring-boot-starter</artifactId><version>4.4.0</version></d......
  • 【浅学】星火知识库文档检索生成问答Demo实测
    前置准备用讯飞大模型3.5搭建好应用,具体操作可以看我的这篇:讯飞星火大模型API,实名认证免费领一年有效期的200万Token,在控制台的左侧有星火知识库,实名认证过就可以开通免费的部分。用这个纯粹是因为免费,关于这个大模型的使用体验啥的不做评价,大家可以也选择自己喜欢的其他模......
  • 【SpringBoot3+Mybatis】小程序和后台管理系统 员工/分类/菜品/套餐管理 上传文件 CRU
    文章目录一、项目介绍&Github二、技术选型三、开发环境搭建四、员工管理4.1新增员工①sql②对象拷贝DTO与Entity③异常捕获与处理④动态获取当前登录者Id⑤ThreadLocal4.2员工分页查询①请求参数实体与响应数据实体②controller层③service层使用pageHelper......
  • [QLIE] 封包接口Hook
    [QLIE]封包接口Hook这个主题快拖了半个月,中间一直没空写,今天看着实在有点久了,必须写一写了,不然就快忘记了。起因前不久HappyLiveShowUp发了官中,但是又搞的奇奇怪怪的加密,很是无聊,稍微调了下和之前ハミダシクリエイティブ官中是挺像的。steam的dll是用Themida保护的,其......
  • Mybatis的接口映射原理
    1、问题引入在使用Mybaits时,只需要写一个Mapper接口(不用写实现类),并在对应的xml文件中写好sql。然后,Mybatis就自动实现了具体的CRUD方法调用。通常我们使用Mybatis的主要步骤是:构建SqlSessionFactory(通过xml配置文件,或者直接编写Java代码)从SqlSessionFactor......
  • SpringBoot手动取消接口执行方案
    实际开发中经常会遇到比较耗时的接口操作,但页面强制刷新或主动取消接口调用后后台还是会继续运行,特别是有大量数据库操作时会增加服务器压力,所以进行研究测试后总结了一套主动取消接口调用的解决方案自定义注解用于标记耗时接口@Retention(RetentionPolicy.RUNTIME)@Target({El......
  • ISBN信息查询api接口
     基本说明:接口地址:http://data.isbn.work/openApi/getInfoByIsbn?isbn={isbn}&appKey={appkey}返回格式:json请求方式:get请求示例:http://data.isbn.work/openApi/getInfoByIsbn?isbn=9787513159074&appKey=ae1718d4587744b0b79f940fbef69e77伽薇 809137232请求参数说明:名......
  • 接口注意的点
    参考:http://mp.weixin.qq.com/s?__biz=Mzk0ODYyNjE4NA==&mid=2247486325&idx=1&sn=eadb10489f62167bb628f3f89828c613&chksm=c365fd12f4127404b3351138ddfd38934644046777942dccd4d3742de7e2d0198214fa364df8&mpshare=1&scene=24&srcid=03262a33of......
  • 分析回调接口的记录
    分析回调接口的一个重要指标就是:方向性。WhycanextendsainterfacegetacallbackinJava?BurpSuite提供了一个标准的API接口,插件开发者需要实现其中的某些接口和方法,并通过BurpSuite提供的扩展性框架注册和加载插件。BurpSuite在运行时会自动发现并调用插件中实现的特......