Apidoc的安装配置及使用

Apidoc的安装配置及使用

  • Apidoc的安装配置及使用
    • 1.什么是Apidoc
    • 2.友好的文档展示页面
    • 3.注释生成接口文档的原理
    • 4.Apidoc安装
    • 5.Apidoc使用
    • 6.常用Apidoc注释规则举例
    • 7.PHPstorm中设置配置参考

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
  1. 验证安装是否成功:
# 出现帮助信息则安装成功
apidoc -h 
  1. 配置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}
*/

你可能感兴趣的:(#,PHP,后端,#,API文档)