php - Api 接口写法规范和要求
前言
说明
apidoc是一个API文档生成工具, apidoc可以根据代码注释生成web api文档, apidoc从注释生成静态html网页文档,不仅支持项目版本号,还支持api版本号
安装
A). 系统需要安装nodejs(略)
B). 安装apidoc
# 有些系统需要sudo 权限来安装
$ npm install apidoc -g
C). 执行生成
# 这个文档的生成规则是
# apidoc
# -i code_dir
# -o output_dir
$ apidoc -i myapp/ -o apidoc/ # 对于项目中我们使用 laravel artisan 封装了一个函数
# 生成 api doc 文档
$ php artisan lemon:doc apidoc
注意: 分组名不支持中文,可修改
使用
A) 生成文档
$ apidoc -i myapp/ -o doc/api [-c ./] -f ".*\.js$"
-i
表示输入,后面是文件夹路径 <br/>
-o
表示输出,后面是文件夹路径 <br/>
默认会带上-c
,在当前路径下寻找配置文件apidoc.json
,如果找不到则会在package.json中寻找"apidoc": { }
<br/>
-f
为文件过滤,后面是正则表达式,示例为只选着js文件 <br/>
-e
的选项,表示要排除的文件/文件夹,也是使用正则表达式
B) 项目配置
{"name" : "项目名","version": "1.0.0","title": "mysails-浏览器标题","description": "description"
}
我们的配置存放在根目录 package.json
文件中.
参数说明和示例
apidoc
支持如下关键字:(下面 [ ] 中括号中表示是可选写的内容,使用时不用加 [ ] 中括号。)
@api {method} path [title]只有使用@api标注的注释块才会在解析之后生成文档,title会被解析为导航菜单(@apiGroup)下的小菜单method可以有空格,如{POST GET}@apiGroup name分组名称,被解析为导航栏菜单@apiName name接口名称,在同一个@apiGroup下,名称相同的@api通过@apiVersion区分,否者后面@api会覆盖前面定义的@api@apiDescription text接口描述,支持html语法@apiParam [(group)] [{type}] [field=defaultValue] [description]详细介绍见: http://apidocjs.com/#param-api-param@apiVersion verison接口版本,major.minor.patch的形式@apiIgnore [hint]apidoc会忽略使用@apiIgnore标注的接口,hint为描述@apiSampleRequest url接口测试地址以供测试,发送请求时,@api method必须为POST/GET等其中一种@apiDefine name [title] [description]定义一个注释块(不包含@api),配合@apiUse使用可以引入注释块在@apiDefine内部不可以使用@apiUse
@apiUse name引入一个@apiDefine的注释块@apiHeader [(group)] [{type}] [field=defaultValue] [description]@apiError [(group)] [{type}] field [description]@apiSuccess [(group)] [{type}] field [description]用法基本类似,分别描述请求参数、头部,响应错误和成功group表示参数的分组,type表示类型(不能有空格),入参可以定义默认值(不能有空格),field上使用[]中扩号表示该参数是可选参数@apiParamExample [{type}] [title] example@apiHeaderExample [{type}] [title] example@apiErrorExample [{type}] [title] example@apiSuccessExample [{type}] [title] example用法完全一致,但是type表示的是example的语言类型example书写成什么样就会解析成什么样,所以最好是书写的时候注意格式化,(许多编辑器都有列模式,可以使用列模式快速对代码添加*号)
写法规范
参数对齐
/*** @api {get} /api_prefix/check_verification [O]验证验证码* @apiVersion 1.0.0* @apiName HomeCheckVerification* @apiGroup Home* @apiParam {String} mobile 手机号* @apiParam {String} captcha 验证码*/
public function checkVerification(){}
apiName命名规范
apiName 的命名规范是 apiGroup + functionName;
apiName 的写法规范是 首字母大写的驼峰模式
例如上面的命名规范是
apiGroup : Home
apiName : HomeCheckVerification
返回值约定
数字类型, 需要转换成int 类型(返回的json 串中不需要有引号包裹)
文字类型的, 需要转换成 string 类型
返回值中不允许存在
null
返回值对齐
返回的类型值, 参数值, 说明必须对齐
返回的参数值和真正返回的内容值必须填写完整
/*** @api {get} /api_prefix/version [O]检测新版本(Android)* @apiVersion 1.0.0* @apiName HomeVersion* @apiGroup Home* @apiParam {String} version 版本号* @apiSuccess {String} download_url 下载地址* @apiSuccess {String} description 描述* @apiSuccess {String} version 版本* @apiSuccessExample data:* {* "download_url": "http:\/\/domain.com\/1.1.1.apk",* "description": "修改bug若干, 增加微信支付功能",* "version": "1.1.1"* }*/
public function version()
路由定义
api 路由文件存放在 app/Http/Routes/
文件夹下
Routes/api_dailian.phpapi_up.php...
使用的PHP组件
系统使用 dinggo 作为 api的封装组件
dingo/api 中文文档
其他说明
A). 接口命名
lists => 列表
create => 创建
edit => 编辑
delete => 删除
B). 参数命名
例如 A下的传递参数, 我们应当使用 title 而不能使用
C). 路由命名
路由的名称和坐在分组还有函数名进行匹配, 使用蛇形写法
/*** @api {get} /dailian/bank/lists [O][B]银行账户列表* @apiVersion 1.0.0* @apiName UserBankList* @apiGroup User* @apiSuccess {String} id 账号ID* @apiSuccess {String} bank_account 账号信息* @apiSuccess {String} bank_true_name 真实姓名* @apiSuccess {String} bank_type 账号类型 : 支付宝* @apiSuccess {String} note 备注* @apiSuccessExample 成功返回:* [* {* "id": 2,* "bank_account": "123123123",* "bank_true_name": "二狗",* "bank_type": "支付宝",* "note": ""* }* ]*/
public function lists()
这里的命名是 api_dailian.bank_lists
D). 自营的接口无特殊返回不需要填写说明
E). 接口中只能返回有意义的数据, 对app无用的数据不得返回
F). 列表为空也需要返回分页
php - Api 接口写法规范和要求相关推荐
- Restful API是什么?初探Restful API,传统接口写法与Restful API接口写法区别
Restful API是什么?初探Restful API?为什么要用Restful API?传统接口写法与Restful API接口写法区别,带着这些问题我们来具体了解下Restful API: 目录 ...
- 【编程规范】 后端API接口设计编写与文档编写参考
文章目录 0 统一规范 0.1 理清业务流程 0.2 定义前后端开发的接口规范 0.3 定义接口文档 1 后端接口编写 1.0 后端接口介绍 1.0.1 接口交互 1.0.2 返回格式 1.0.3 C ...
- restfull api 接口 规范
restfull api 接口 规范 1 这种接口 可以根据客户端 的要求类型返回不同的类型的 表现形式,比如返回json,返回xml,返回纯文本. 2 这种接口 不同的操作就得用不同的方法 get ...
- API接口通讯参数规范(2)
针对[API接口通讯参数规范]这篇文章留下的几个问题进行探讨. 问题1 试想一下,如果一个http请求返回一个500给我们,那我们是不是都不用看详情都知道该次请求发生了什么?这正是一个标准的结果码意义 ...
- Drf从入门到精通一(API接口、Postman、Restful规范、序列化、快速使用drf、CBV源码分析)
文章目录 一.前后端开发模式 二.API接口 三.接口测试工具Postman 四.Restful规范 五.序列化反序列化 六.DjangoRestFramework快速使用 七.CBV源码分析 一.前 ...
- Swagger3 API接口文档规范课程(Java1234)(内含教学视频+源代码)
Swagger3 API接口文档规范课程(Java1234)(内含教学视频+源代码) 教学视频+源代码下载链接地址:https://download.csdn.net/download/weixin_ ...
- Android开发规范:API接口安全设计规范
公众号[国民程序员]回馈粉丝福利: 现金红包和送书活动火热进行中,点击参与! 我的新书<Android App开发入门与实战>已于2020年8月由人民邮电出版社出版,欢迎购买. 书籍详情请 ...
- 大厂对外提供的API接口入参命名规范
最近查阅百度API接口时,发现接口文档中,参数明文居然是下划线格式,很疑惑.进一步查阅了 阿里开发平台.腾讯微信开发者平台, 对外api接口都是下划线命名, 为什么? java实体类的属性一般是遵从 ...
- 前端请求restful风格接口怎么传参_浅谈Restful API 的请求规范
前言 在SpringMVC架构上进行开发,开发者一直在使用jsp.valocity或者其他页面模版作为表现层面,前端工程师需要将设计师的设计图转换为静态的html页面,然后交付给后端将静态的html页 ...
最新文章
- 【iCore4 双核心板_ARM】例程五:SYSTICK定时器 实验——定时点亮LED
- open函数和close函数的使用
- Oracle - 新装数据库、新建用户注意事项
- 蓝色大巴汽车网站404页面源码
- (20)System Verilog接口interface设计示例
- 模板设计模式_C常用设计模式——模板方法模式
- tcp码流中查找rtp头_跟踪数据流中的时间以查找性能问题
- 接口测试-接口定义功能-前端-实现动态增删表单
- 四 akka学习 四种多线程的解决方案
- 帮你理解vue的数据绑定的流程
- 博弈论学习(一)——基础
- android otg dac,随身HiFi 安卓OTG功能在音频上的妙用
- 使用Navicat导入“中国5级行政区域mysql库”
- 编译安装cacti-spine
- abp core Oracle,ABP适配Oracle全过程
- (69)zabbix监控惠普打印机
- 移动终端软件测试基础知识,移动终端软件测试基础知识 - Mr.南柯 - 51Testing软件测试网 51Testing软件测试网-软件测试人的精神家园...
- CameraX Java 1.0.0-alpha10 安卓开发
- 信安软考 第十九章 操作系统安全保护
- 钱宝网可靠吗? 不信可以先试用后在说
热门文章
- SpringBoot响应Json数据乱码通过配置解决
- Eclipse新建Maven项目没有web.xml
- 交互式计算机图形学总结:第五章 光照和明暗绘制
- Scrum sprint plan中规模估算的常见方式
- tcp port numbers reused出现原因_python socket(tcp 线程)实现简单聊天室
- dac0832产生梯形波程序C语言,在8086系统中用DAC0832输出一个三角波,一个梯形波,和一个正弦波。...
- win7 php mysql扩展名_win7下MySQL 5.1.73安装过程(图解)并在php.ini中启用相关扩展。...
- 用Delphi开发OPC客户端工具的方法研究
- HTML5 拖拽的简单实践
- 【Touchinput 】触摸和输入 概述(1)