秘密兵器のチーム効率的な共同開発
1.はじめに
チーム開発では、私はあなたがそのような問題が発生していないか分かりません。
リットルの新規参入者にはプロジェクトのドキュメントが存在しないので、唯一のビジネスロジックを見つけるために、トレースルートに依存しているコード分析を読み取ることができ、プロジェクトコードを引き継ぎました
Lフロントページには、データを取得するために、対話型のリクエストを書くために、バックエンドインターフェース規則を待って、クラスメートを書か
プロジェクトはまだ完了していないので、Lテストの学生は、テストケースを書き、彼らは開始できませんでした
それはどのように喜んで上記の問題を解決するには？答えは、それがあることである --APIDOC。
2.APIDOCは何ですか
APIDOCは、プロジェクトのバージョンをサポートしていないだけで、自動的にコードのコメントに基づいて、静的なHTMLページのドキュメントを生成できるWeb APIドキュメント生成ツールでも、インターフェースのアップグレード版の後にインターフェースのバージョン番号をサポートし、インタフェースのドキュメントを簡単に読んで比較することができます。このようなインタフェースのドキュメント生成ツールは、Java言語は、Javadocを持っているなど、PHP言語はたPHPDocがあり、多くは、Python言語は、我々はそれを使用することを選択すべき理由などPydocを、持っている、それはそれは、クロスランゲージ、あなたはJSを使用しているかどうか、ルビー、ジャワ、PHP理由、パイソン、＃... C、限りルールによって書かれたコメントとして、兄弟の前端と後端を使用することができます。私たちはそれをその力を目撃するために協力しましょう。
3.使用の効果を見てみましょう
全体的に一目〜
図 1
明確に理解、それを読むよりも、それを変更するためのインタフェース〜
図 2
テストのうち、あなたがテストケースを書き始めることができ、戻り値のデータを見てみましょう -
図 3
4.具体的な実施プロセス
0x01のインストール
Windows環境下でのインストール：
- 公式サイト nodejs.orgダウンロードnodejs
- インストールした後、NPMを淘宝網ミラーcnpmを置き換えます
ASLインストール-g cnpm --registry = HTTPS：//registry.npm.taobao.org
3. cnpmインストールapidoc
cnpm install apidoc -g
0x02 用法
apidoc -i myproj/ -o mydoc/ [-c ./] -f ".*.js$"
-i 表示输入，myproj是项目文件夹路径
-o 表示输出，mydoc是要生成的接口文档路径
默认会带上-c，在当前路径下寻找配置文件(apidoc.json)
-f 为文件过滤，后面是正则表达式，示例为只选js文件
与-f类似，还有一个 -e 的选项，表示要排除的文件/文件夹，也是使用正则表达式
0x03 配置
新建apidoc.json文件，可参照官方配置示例
{
"name": "example",
"version": "0.0.1",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
我的配置如下:
{
"name": "APP项目接口",
"version": "0.0.1",
"description": "测试文档",
"title": "APP项目接口",
"url" : "http://www.api.com/v1",
"sampleUrl" : "http://www.api.com/v1",
"order": ["User","Article"],
}
配置属性简单介绍
name：项目名称
version：项目版本
description：项目介绍
title：浏览器显示的标题内容
url：请求的前缀，例如https://api.github.com/v1
sampleUrl：如果设置了，则在api文档中出现一个测试用的from表单
order：用于配置输出接口组的顺序
0x04 操作
1.在含有apidoc.json的文件夹(例如myproj)下新建myapp文件夹和mydoc文件夹，在myapp文件夹下新建user.php(注意文件格式要保存为utf-8，否则生成的API文档带中文的注释会产生乱码),我的user.php部分代码如下：
<?php
class User
{
/**
* @api {POST} /register 注册用户
* @apiGroup User
* @apiVersion 0.0.2
* @apiDescription 用于注册用户
* @apiParam {String} account 用户账户名
* @apiParam {String} password 密码
* @apiParam {String} mobile 手机号
* @apiParam {int} company = 0 是否注册企业用户 0 普通用户 1 企业用户
* @apiParam {String} [recommend] 邀请码
* @apiSampleRequest http://www.api.com/server.php
* @apiParamExample {json} 请求样例：
* ?account=test&password=11223344&mobile=182xxxx2345&company=0&recommend=
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"注册成功"}
*/
public function register () { # code... }
/**
* @api {POST} /login 用户登录
* @apiGroup User
* @apiVersion 0.0.1
* @apiDescription 用于用户登录
* @apiParam {String} userName 用户名
* @apiParam {String} password 密码
* @apiParamExample {json} 请求样例：
* ?userName=张三&password=11223344
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {String} code 0 代表无错误 1代表有错误
* @apiSuccess (200) {String} user 用户信息
* @apiSuccess (200) {String} userId 用户id
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"登录成 功","userId":"1"}
*/
public function login() { # code... }
}
2.回到myproj文件夹下，按住shift键并点击鼠标右键选择“在此处打开命令窗口”，在cmd命令窗口中执行如下命令：
apidoc -i myapp/ -o mydoc/
3.打开mydoc文件夹可以看到生成了含有index.html的网页文档，用浏览器打开index.html文件即可浏览文档效果图。
5.遇到的问题
问题一：
在浏览器打开静态文档下，选择相关接口，发送请求，收不到返回的json数据，打开浏览器F12中选择console可以看到，存在跨域问题。
解决办法：
将生成的api文档mydoc文件夹放在访问接口的同域名下（如使用效果图图3），通过域名访问该index.html文件。
问题二：
使用效果图中的接口组名（@apiGroup参数对应值）-“User”和“Article”换成中文后，在浏览器中打开显示为乱码。
解决办法：
主要是 @apiGroup 不支持utf-8 字符串，仅支持ascii码。官方有个办法可以实现utf-8字符串放置在@apiGoup 中。 代码如下：
/**
* @apiDefine User 用户接口
*/
/**
* @api {POST} /login 用户登录
* @apiGroup User
*/
解决效果
图4
6.总结
以上只是抛砖引玉，apidoc还有更多的用法，具体的介绍可以去官网查看，快来动手练练吧，掌握这款工具，带领团队吃鸡，无往而不利 。