Apidoc的安装配置及使用
Apidoc的安装配置及使用
1.什么是Apidoc
Apidoc是一款可以由源代码中的注释直接自动生成api接口文档的工具,它几乎支持目前主流的所有风格的注释。可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等语言中使用
2.友好的文档展示页面
3.注释生成接口文档的原理
apidoc的原理是扫描你的代码文件,提取出注释部分,根据一些规则生成相应的文档。默认的模板久简洁美观,十分适合作为api文档的生成器。
4.Apidoc安装
环境:需要使用npm安装,如果没有安装npm,请先去https://www.npmjs.com/下载npm并且安装。npm官网需要注册账号,另一种方式是安装node,会自动安装npm工具 安装node教程
- 安装:
npm install apidoc -g
- 验证安装是否成功:
# 出现帮助信息则安装成功
apidoc -h
- 配置apidoc.json文件:
{
"name": "appleFarm", //文档项目名
"title": "appleFarmAPI", //html标题
"description":"API接口文档", //文档描述
"url" : "https://www.google.com", //公共接口地址
"version": "0.1.0" //文档版本
}
5.Apidoc使用
# 生成文档的命令
apidoc -i /dir -o /src
/dir:指定源文件目录
/src: 生成接口文档的源文件 public/static : 生成的接口文档地址(一般放在静态文件夹下)
6.常用Apidoc注释规则举例
@api {post} add_team 新建球队 => {请求方式} 路由 接口名称
@apiGroup team => 分组的名称,方便管理分组
@apiParam {String} name 名字. => {参数类型} [参数名] 参数描述
@apiSuccess {String} msg 详细信息. => {响应的类型} 参数 响应描述
@apiSuccessExample Success-Response: => 成功返回的示例,可返json
@apiErrorExample {json} Error-Response: => 失败返回的示例,可返json
@apiDescription This is the Description => 接口的描述
7.PHPstorm中设置配置参考
在 Preferences 搜索 File and Code Templates, 点击Includes进行设置
# PHP Class Doc Comment
/**
* Class ${NAME} Description
* Created by ${PRODUCT_NAME}.
* Created Time ${DATE} ${TIME}
*
* PHP version 7.1
*
* @category ${NAME}
#if (${NAMESPACE}) * @package P:${NAMESPACE}
#end
* @author ${USER} <${USER}@lightserver.cn>
* @license https://www.lightserver.cn Apache2 Licence
* @link https://www.lightserver.cn
*/
# PHP Field Doc Comment
/**
* Class ${CLASS_NAME} Description
* Created by ${PRODUCT_NAME}.
* Created Time ${DATE} ${TIME}
*
* PHP version 7.1
*
* @category ${NAME}
#if (${NAMESPACE}) * @package P:${NAMESPACE}
#end
* @author ${USER} <${USER}@lightserver.cn>
* @license https://www.lightserver.cn Apache2 Licence
* @link https://www.lightserver.cn
*/
# PHP File Header
/**
* Class ${NAME} Description
* Created by ${PRODUCT_NAME}.
* Created Time ${DATE} ${TIME}
*
* PHP version 7.1
*
* @category ${NAME}
#if (${NAMESPACE}) * @package P:${NAMESPACE}
#end
* @author ${USER} <${USER}@lightserver.cn>
* @license https://www.lightserver.cn Apache2 Licence
* @link https://www.lightserver.cn
*/
# PHP Function Doc Comment
/**
* Fun ${NAME} Description
* Created Time ${DATE} ${TIME}
* Author ${USER} <${USER}@lightserver.cn>
*
${PARAM_DOC}
*
#if (${TYPE_HINT} != "void") * @return ${TYPE_HINT}
#end
${THROWS_DOC}
*/
来源:CSDN
作者:lightserver.cn
链接:https://blog.csdn.net/qq_32828933/article/details/103585328