apidoc 使用说明

北慕城南 提交于 2020-01-20 00:07:56

安装环境

安装nodejs和npm
进入官网 https://nodejs.org/en/ 下载首页推荐的版本就可以
在这里插入图片描述
安装完成后

node -v
v8.12.0

说明安装成功,安装nodejs的同时,一并会把npm也替我们安装好,同样使用cmd查看npm版本

npm -v
v6.4.1

安装完成~

安装apidoc
使用npm进行安装

npm install apidoc -g

使用apidoc -h
可以查看帮助 说明安装成功

开始使用

使用apidoc (PHP项目为例)
新建一个项目或者在老项目根目录创建 apidoc.json 文件

apidoc.json

{
  "name": "appleFarm", //文档项目名
  "title": "appleFarmAPI", //html标题
  "description":"appleFarmAPI接口文档", //文档描述
  "url" : "https: //xxx.com",//公共接口地址
  "version": "0.1.0" //文档版本
}

创建src目录,新建 test.php 文件
添加apidoc注释

test.php

class Home {
        /**
         * 定义一个变量 用于apiGroup 因为不支持直接输入中文
         * @apiDefine test 测试
         */
        
        /**
         * @api {post} /Index/getVip 获取vip列表   页面加载时自动获取
         * @apiName GetUser
         * @apiGroup test
         *
         * @apiParam {string} req1 请求值
         *
         * @apiSuccess {String} res1 返回值1
         * @apiSuccessExample Success-Response:
         * {
         *   res1:"test"
         * }
         */
        public function test(){
        }
}

保存完毕之后 我们使用apidoc 命令进行生成文档(项目根路径下执行,也就是有apidoc.json文件的路径)

apidoc -i src/ -o apidoc/
info: Done.

该命令会把所有文件接口注释全部生成文档,放到apidoc目录下,我们进去点开index.html 就可以看到
在这里插入图片描述
至此,文档生成完毕。

apidoc相关的注释

@api {get} /users/:user_id Request User Information
最主要的参数,”{get}”定义了HTTP请求是GETAPI地址是”/users/:user_id”,文档中API的名称是”Request User Information”。

@apiVersion 0.1.0
API的版本号,默认显示在API名称的右方。该参数可用来在不同的版本之间做比较,后面会介绍。

@apiName GetUser
API名称,不影响文档。

@apiGroup User
API分组名,文档内容中和菜单栏中同一组的API会在一同显示,方便阅读。

@apiPermission admin
API的访问权限,文档中默认会API地址下面显示。没有权限要求的话,此项可以省略。

@apiDescription API to get the user information.
API的详细描述,默认显示在API名称的下方。

@apiExample Example usage:
API调用示例,该参数的下一行就是示例的内容,直到有空行结束。可以定义多个@apiExample,默认在文档中会以标签形式列出,标签名就是”Example usage:”。

@apiParam {Number} user_id The user’s unique ID.
API参数字段介绍,”{Number}”定义了字段类型,”user_id”是字段名称,后面则是字段描述。可以定义多个@apiParam字段。

@apiSuccess {String} name Name of the User.
API成功后返回的字段,如同@apiParam,”{String}”定义了字段类型,”name”是返回字段名称,后面则是字段描述。可以定义多个@apiSuccess字段。

@apiSuccessExample {json} Success-Response:
显示一个API成功返回后Response响应的示例,”{json}”代表响应体是JSON类型。该参数的下行就是响应体内容,直到有空行结束。可以定义多个@apiSuccessExample,默认在文档中会以标签形式列出,标签名就是”Success-Response:”。

@apiError UserNotFound User was not found.
API发生错误后的返回,”UserNotFound”是错误名称,后面则是错误描述。可以定义多个错误返回。

@apiErrorExample {json} Error-Response:
显示一个API错误返回后Response响应的示例,”{json}”代表响应体是JSON类型。该参数的下行就是响应体内容,直到有空行结束。可以定义多个@apiErrorExample,默认在文档中会以标签形式列出,标签名就是”Error-Response:”。

@apiSampleRequest http://localhost:5000/users/:user_id
文档提供的API Sample测试的地址。其实在”apidoc.json”中配过”sampleUrl”项后,此参数即可省去,除非这个API的测试URL比较特殊,需特别指定。

原文:https://www.jianshu.com/p/d324810d694d

标签
易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!