apiDocとは、その使い方を解説する！
APIをよく取り扱っている場合は、Apidocというものをよく耳にしていますね。それでは、Apidocとは何ですか？何かを実現できますか？本文では、これらの質問に対して、Apidoc及びその使い方を完全に解説していきます。
APIをよく取り扱っている場合は、apiDocというものをよく耳にしていますね。それでは、apiDocとは何ですか？何かを実現できますか？本文では、これらの質問に対して、apiDoc及びその使い方を完全に解説していきます。また、apiDocに完全互換できるGUIツールのApidogを使って、より簡単で効率的にAPIを管理する方法も一緒に紹介します。
apiDocとは
apiDocjsは、RESTful Web APIのドキュメントを自動生成するためのオープンソースツールです。ソースコードに記述された特別なアノテーション(注釈)からドキュメントを生成します。
公式サイト：
主な特徴は以下の通りです。
- 自動ドキュメント生成
ソースコードのアノテーションを解析することで、手動での書き込みは不要になります。 - アノテーションベース
開発者は@api、@apiName、@apiGroupなどの独自アノテーションをコードに記述し、そこからAPIのエンドポイント、パラメータ、レスポンスフォーマットなどの情報を取得します。 - APIドキュメントテンプレート
Handlebars、Bootstrap、RequireJS、jQueryを使った標準のHTMLテンプレートが用意されています。生成されたドキュメントはインタラクティブなHTMLページとして出力されます。 - 複数言語をサポート
当初はJavaScript/Node.jsのAPIが対象でしたが、現在はJava、PHP、Go、Ruby、Pythonなど多くの言語をサポートしています。 - カスタマイズ可能な出力
デフォルトのテンプレートはカスタマイズが可能で、設定やテンプレートファイルの上書きで、プロジェクトに合わせたブランディング、スタイル調整ができます。 - 開発ワークフローに統合可能
Grunt、Gulp、npmスクリプトなどのビルドツールと連携させることで、コード変更の度にドキュメントを自動更新できます。
apiDocjsの主なメリットは、ソースコードに密着したアノテーションベースのドキュメント生成で、手作業の手間が省け、見栄えの良いインタラクティブなドキュメントが生成できる点です。一方で、ドキュメントの正確性を保つためには、コードベースへの継続的なアノテーション記述が求められます。
apiDocの動作要件
Apidocを利用するために、次の動作要件が必要となります。
- Node.js (8.x以上)
ApidocはNode.jsで動作するツールのため、まずはNode.jsのインストールが必要です。
- npm
Apidoc自体はnpmパッケージとして配布されているため、npmコマンドが利用できる必要があります。
- ソースコード
ドキュメントを生成する対象となるAPIのソースコードが必要です。JavaScriptで記述されている必要があります。
- テンプレートエンジン
デフォルトではHandlebarsを使用しますが、PugやEJSなど他のテンプレートエンジンも利用可能です。
- テーマ
カスタムテーマを使用する場合はHTML/CSS/JavaScriptに対応したテーマファイルが必要になります。
以上のように、Apidoc自体はNode.jsとnpmさえインストールできれば簡単に利用できますが、テーマカスタマイズなど高度機能を利用するには、さらに専門様式が求められます。
使い方：apiDocを使いこなす
それでは、Apidocをどうやって利用すれば良いのでしょうか。次は、Apidocを利用するための詳細手順を皆さんに紹介します。
apiDocのインストール
次のコマンドラインを使って、Apidocをパソコンにインストールすることができます。
$ npm install apidoc -g
ソースコードにApidoc形式のコメントを記述する
Apidocでは、ソースコード中に特殊な形式のコメントを記述することで、ドキュメントの情報を記述します。具体的には以下のような形式のコメントを記述します。
/**
* @api {get} /users/:id Get User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/
@apiで始まる行がApidocのコメント記法です。
- @api {HTTPメソッド} {エンドポイント} {タイトル}
- @apiName {操作名}
- @apiGroup {カテゴリ}
- @apiParam {パラメータ}
- @apiSuccess {レスポンス}
などの形式で記述していきます。
Apidocはこれらのコメントをパースして、ドキュメントを生成します。このようにソースコードとドキュメントを一元化できるのがApidocの特徴とも言えますね。
apiDocコマンドでドキュメントを生成する
次のコマンドを使用して、docsディレクトリ内にHTMLファイルが生成されます。
$ apidoc -i src/ -o docs/
また、他のオプションとして、ApidocはYmalとJsonフォーマットのデータの生成にも対応できます。ApidocでJSONやYAML形式のデータを生成するには、以下のようにします。
apidocコマンドの-fオプションにjsonまたはyamlを指定します：
# JSON
$ apidoc -i src/ -f json -o docs/
# YAML
$ apidoc -i src/ -f yaml -o docs/
そうすると、指定したフォーマットのファイルが生成される
docs/
├── api_project.json
├── api_project.yaml
生成されたAPIドキュメントを確認
生成されたAPIドキュメントのフォーマットによって、次のいずれかのコマンドを入力して、生成したドキュメントを開いて確認することができます。
#HTML
$ open docs/index.html
# JSON
$ open docs/api_project.json
# YAML
$ open docs/api_project.ymal
template/を編集してドキュメントのテーマをカスタマイズ
Apidocで生成されるドキュメントの見た目をカスタマイズするには、templateディレクトリのファイルを編集する必要があります。
Apidocのテーマは以下のようなファイルから成り立っています。
- template/index.html - ドキュメントのメインページ
- template/layout.ejs - ベースのレイアウト
- template/styles/ - CSSファイル
これらのファイルを直接編集することで、ドキュメントの見た目をカスタマイズできますが、一定の専門知識が必要となります。
apiDocを直感化に、APIをより効率的に作成
Apidocを使って簡単にドキュメントを作れますが、いろんなデメリットや制限も確かに存在していますので、APIをより効率的に作成するには、他のツールの利用を検討する必要もあるのでしょう。
Apidocには以下のような制限があります。
- コメント形式が特殊なため、コメントの記述ミスが発生しやすい
- ドキュメント生成時にソースコードを解析するため、解析性能に制限がある
- 大規模なプロジェクトになるとコメントのメンテナンスが難しくなる
- ドキュメントの自動化が目的のため、詳細な説明記述が苦手
- テーマカスタマイズにはHTML/CSSの知識が必要
- バージョン管理が厳密ではない
そこで、よりAPIを作成して、管理するために、Apidogという完璧なAPI管理ソフトを使用することがおすすめです。Apidogを使用すると、手動でコードを書く必要がなくなり、直感的なGUIでAPIドキュメントを設計したり、APIを作成したりすることができます。それに、Apidogを使用して作成したドキュメントは、誰かにとっても非常に読みやすくなります。
また、ApidogはApidocのファイル、SwaggerのYAMLファイル及びJSONファイルからのインポートをサポートしています。APIをApidogに移行したい場合は、非常に簡単になります。
Apidocで欠けているAPIのバージョンコントロール機能も、Apidogで非常に充実しています。Apidogのバージョンのコントロール機能を導入すると、異なるバージョンのAPIの変更点を表示することができるので、開発者は需要に応じて異なるバージョンを選択できますし、各バージョンの違いと変更をいち早く把握することもできます。
