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教程

1. 安装:

npm install apidoc -g

2. 验证安装是否成功：

# 出现帮助信息则安装成功
apidoc -h 

3. 配置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}
*/