接口编写 文档规范 总结
正文：
一：协议规范
为进一步确保数据交互安全。正式地址（生产地址）必须遵循HTTPS协议。
二：域名规范
每个项目要有且仅有一个自己唯一的域名+端口。在项目配置文件中要添加静态变量专门进行存储。
如果一个域名满足不了要求，那么就需要再添加一个。
格式规范如下：
（java）public static final String URL_BASE = “https://127.0.0.1:8080/”;
（java）public static final String URL_BASE_SUB = “https://192.168.0.1:8080/”;
必须以https开头，并以“/”结尾。
三：API路径规范
作为接口路径，为了和其他路径完美区分，必须在路径中添加api目录
格式规范如下：
（java）public static final String URL_API = “api/”;
（PHP）php目录是加index.php/api/
必须以字母开头，并以“/”结尾。
四：版本控制规范
项目正式上线后，正式版本要确定接口版本、并备份接口代码。
为方便管理，需要在接口路径中加入版本号信息。
格式规范如下：
（java）public static final String URL_VERSION =”v1/”;
必须以字母开头，并以“/”结尾。
更新版本后可以使用v2 v3等、依次递加。
五：API命名规范
根据二：域名规范、三：API路径规范、四：版本控制规范。项目中必须在配置文件中增加BaseUrl静态常量。值=三个相加。
格式规范如下：
（java）public static final String BASEURL=URL_BASE+URL_API+URL_VERSION;
具体代码如下：
BASEURL = [“https://127.0.0.1:8080/api/v1/”]
BASEURL = [“https://127.0.0.1:8080/api/v1/”]
BASEURL = [“https://127.0.0.1:8080/api/v1/”]
重要的事情说三遍。
根据业务需求，可以在v1版本文件夹里创建，一个或者多个接口文件。
一个的规范：
https://127.0.0.1:8080/api/v1/getBanner
这就是一个获取banner的接口。
多个的规范是根据业务需求来区分：
https://127.0.0.1:8080/api/v1/home/getBanner
https://127.0.0.1:8080/api/v1/user/userLogin
新建user文件，里面存放用户级别的操作：如登陆、注册、修改密码等等。
新建sms文件，里面存放对短信的接口操作：如发送验证码、验证手机号等等。
所以，接口方法文件必须要有自己的规范，命名必须统一使用驼峰命名法或者下划线拼接命名法。举个栗子：（upperCamelCase）（upper_camel_case）。所有接口命名方式，必须遵循如下规范。
（1）新增方法：如新增一个地址、新增一个联系人。
命名规范：
必须以“add”为前缀。例如addAddress
事例地址：https://127.0.0.1:8080/api/v1/addAddress
（2）删除方法：如删除一个地址。
命名规范：
必须以“delete”为前缀。例如deleteAddress
事例地址：https://127.0.0.1:8080/api/v1/deleteAddress
（3）修改方法：如修改一个地址。
命名规范：
必须以“updata”为前缀。例如updataAddress
事例地址：https://127.0.0.1:8080/api/v1/updataAddress
（4）获取方法：如获取一个地址。
命名规范：
必须以“get”为前缀。例如getAddress
事例地址：https://127.0.0.1:8080/api/v1/getAddress
（5）获取列表方法：如获取一个地址列表。
命名规范：
必须以“get”为前缀、“List”为后缀。例如getAddressList
事例地址：https://127.0.0.1:8080/api/v1/getAddressList
其他规范：
发送验证码使用‘send’为前缀、保存一个数据以‘save’为前缀、上传图片以‘uploadImage’为名称等等。
具体地址就等于（BASEURL+“address/getAddressList”）
目的：一目了然、降低维护成本。
六：请求参数规范
请求方式：公共数据使用get方式请求，私有数据使用post方式请求。尽量全部是用post。
请求头：请求头根据项目需求添加配置参数。如：accept=‘application/json
’等。请求头根据项目需求可以要求传入用户token、app名称版本、唯一验签码等加密数据。
请求参数：
根据数据库字段进行命名、保持一致最省事。
接口编写 文档规范 总结相关推荐
- 接口对接文档规范2023年最新版（Restful API风格）
接口对接文档 服务共享 1.设计模式 使用Restful API风格, Restful API的优势是具备更好的易用性,让异构系统更容易集成,且开发执行效率比较高,面向资源要求也比较高. 2.设计约束 ...
- RESTful API接口文档规范小坑
希望给你3-5分钟的碎片化学习,可能是坐地铁.等公交,积少成多,水滴石穿,谢谢关注. 前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问 ...
- Swagger3 API接口文档规范课程（Java1234）（内含教学视频+源代码）
Swagger3 API接口文档规范课程(Java1234)(内含教学视频+源代码) 教学视频+源代码下载链接地址:https://download.csdn.net/download/weixin_ ...
- 算法API接口文档规范
算法API接口文档规范 参考:百度AI开放平台:https://ai.baidu.com/ai-doc/FACE/yk37c1u4t 接口功能介绍 1.人脸比对:比对两张图片中人脸的相似度,并返回相似 ...
- 建议：为所有导出的API元素编写文档注释。
如果要想使一个API真正可用,就必须为其编写文档.传统意义上的API文档是手工生成的,所以保持文档与代码同步是一件很繁琐的事情.Java语言环境提供了一种被称为Javadoc的实用工具,从而使这项任务 ...
- 支付宝接口使用文档说明 支付宝异步通知
支付宝接口使用文档说明 支付宝异步通知(notify_url)与return_url. 现支付宝的通知有两类. A服务器通知,对应的参数为notify_url,支付宝通知使用POST方式 B页面跳 ...
- python使用微信设置-微信 python 接口 -- itchat 文档
itchat 一. 安装 $ pip install itchat 特殊的字典使用方式 通过打印 itchat 的用户以及注册消息的参数, 可以发现这些值都是字典. 但实际上 itchat 精心构造了 ...
- Swagger接口在线文档
1.Swagger是什么? Swagger围绕OAS构建RESTFUL文档: Swagger动态生成接口定义文档: Swagger易用免费且开源: Swagger就是将项目中所有的接口展现在页面上,并 ...
- README 规范和项目文档规范
1. README 规范 我们直接通过一个 README 模板,来看一下 README 规范中的内容: # 项目名称<!-- 写一段简短的话描述项目 -->## 功能特性<!-- 描 ...
最新文章
- 如何构建高可用和可伸缩的架构？
- 新项目新工作空间新仓库新setting文件
- HTML5入门之新的选择器
- IOCP不可忽视的细节
- Android Studio开发基础之细节问题笔记
- 最有用的Postgres扩展：pg_stat_statements
- Hibernate通用Dao实现
- 51nod 1013快速幂 + 费马小定理
- 腾讯企业邮箱服务器地址imap端口号,腾讯企业邮箱如何设置IMAP、POP3/SMTP及其SSL加密方式...
- 对996最客观的描述，一叶知秋
- 服务器电脑 默认虚拟内存,服务器是否需要设置虚拟内存
- Go 编码建议——项目布局
- 设计模式系列- 迭代器模式
- iOS开发之NSData和NSString相互转换
- Zookeeper是什么
- KNN算法实现knn完成iris数据集分类
- 小米笔记本linux无线网失效,小米笔记本无线网络打不开怎么办
- 适当的发泄 有助于自我调整
- aria2 txt导入_使用Aria2完成下载任务
- 1-Scrapy Tutorial