apidocインストールチュートリアル:
1、我々は最初にすでにインストールされたか否かを判断しなければならないNode.jsのインストールされていない場合は、インストールガイドのNode.jsを参照することができます。https://blog.csdn.net/ba_qi/article/details/103177812
図2は、apidocを利用することができるNPMにコマンドを入力し、迅速にインストールする apidocの-gをインストールNPM 下に示すように、apidocインストール用:
次の図に示すインストールは完了です。
図3に示すように、入力apidoc -v コマンド以下に示すようにインターフェイスが表示された場合、正常にインストールさapidocを示し
apidocの使用:
apidoc 次のようにいくつかの重要なパラメータ:
パラメータ |
説明 |
-f |
、正規表現をサポートして、キャッシュ内のファイルを選択します。-fパラメータは複数回使用することができ、式の複数の異なる-fに対応することができます。以下のような:。。 "* \ $ JS" apidoc -f -f "* \\ $ TS" |
-私 |
ソースコード位置を選択します。以下のような:apidocのMyApp -i / |
-o |
結果のオブジェクトは、ファイルの場所を選択します。以下のような:apidoc -o apidoc / |
-t |
ファイルを生成するテンプレートを選択し、カスタムテンプレートを作成して使用することができます。(著者注:これまでのところ、私は、このパラメータを使用していません) |
-h |
コマンドの大半と同様に、このパラメータは、ドキュメントをプリントアウトすることができます |
1 |
apidoc -iのsrc / -o apidoc /#ディレクトリapidocにsrcディレクトリのファイル、およびこれらのファイルを検索してすぐに文書ファイルを生成することができます。 |
1 |
apidoc -h#表示ヘルプ情報 |
使用apidoc
一般的なファイルのディレクトリ結果を図3に示します。
どこで:
apidoc.json:apidocプロジェクトレベルの設定ファイルは、プロジェクト全体のトップレベルのディレクトリに配置する必要があります。
Demo1.javaは:デモデモのソース・ファイルのために、それはトップレベルのディレクトリとそのサブディレクトリ全体をプロジェクトディレクトリの下に配置することができます。apidocは、可能なすべてのソースファイルを選択するために、プロジェクト全体のディレクトリを検索します。
次のように含まれるコードDemo1.javaのapidoc.jsonは以下のとおりです。
1 2 3 4 5 6 7 |
{ 「名前」:「デモ」、 "バージョン": "1.0.0"、 「説明」:「これはデモシンプルapidocです」、 「タイトル」:「デモ」、 "URL": " https://api.github.com/v1 " } |
1 2 3 4 5 6 7 8 9 10 |
/ ** * @api {GET} /ユーザ/:ID要求ユーザ情報 * @apiName GETUSER * @apiGroupユーザー * * @apiParam {数値} IDユーザー固有のID。 * *ユーザーの@apiSuccess {文字列} FIRSTNAMEファーストネーム。 * @apiSuccess {文字列}者の姓をLASTNAME。 * / |
シェル入力apidoc -i ./ -o ../../public/docのコマンド、以下に示すように場合に生じる完了結果は同じディレクトリにあり、文書が生成されたことを示すapidocと(-o ../ ../public/docの対応)ディレクトリ
打开../../public/doc目录,可以看到如下图所示的静态Web文件。
浏览器中访问index.html就可以看到生成在线接口文档网站
配置
apidoc.json文件是项目级的配置文件,接下来简单地介绍一下其中常用的配置项。
配置名 |
描述 |
name |
工程名。如果该字段不存在,则apidoc会尝试通过package.json(apidoc顶层配置文件)来生成 |
version |
工程文档的版本号。如果该字段不存在,则apidoc会尝试通过package.json(apidoc顶层配置文件)来生成 |
description |
工程详细描述。如果该字段不存在,则apidoc会尝试通过package.json(apidoc顶层配置文件)来生成 |
title |
文档标题,显示在文档界面的最上方 |
url |
整个api url的前缀,接下来的所有接口url都会加上这个前缀 |
sampleUrl |
api示例的url前缀。如果设置了这个值,则界面中显示请求表单,可以用于测试接口 |
header |
|
title |
文档头(header)的连接锚点名 |
filename |
文档头所使用的文件 |
footer |
|
title |
文档尾(footer)的连接锚点名 |
filename |
文档尾所使用的文件 |
order |
接口的排列顺序list,如果不指定,则由apidoc自行确定 |
一个比较完整的配置文件如下:
{
"name": "demo",
"version": "1.0.0",
"description": "这是一个简单的apidoc的demo",
"title": "api接口demo",
"url": "https://api.github.com/v1",
"sampleUrl": "https://api.github.com/v1/test",
"header": {
"title": "接口文档",
"filename": "header.md"
},
"footer": {
"title": "footer",
"filename": "footer.md"
},
"order": [
"Error",
"Define",
"PostTitleAndError",
"PostError"
]
}
更多的配置项请参考apidoc官方文档站点。