Apidog

オールインワンのAPI開発プラットフォーム

API設計

API仕様書生成

API設計

API Mock

APIテスト自動化

無料登録
Home / 操作ガイド / Apidocとは、その使い方を解説する!

Apidocとは、その使い方を解説する!

APIをよく取り扱っている場合は、Apidocというものをよく耳にしていますね。それでは、Apidocとは何ですか?何かを実現できますか?本文では、これらの質問に対して、Apidoc及びその使い方を完全に解説していきます。

APIをよく取り扱っている場合は、Apidocというものをよく耳にしていますね。それでは、Apidocとは何ですか?何かを実現できますか?本文では、これらの質問に対して、Apidoc及びその使い方を完全に解説していきます。また、Apidocに完全互換できるGUIツールのApidogを使って、より簡単で効率的にAPIを管理する方法も一緒に紹介します。

button

Apidocとは

apidocは、RESTfulなWeb APIのドキュメントを自動生成するツールです。YAMLやJSONなどのAPI記述フォーマットとは異なり、Apidocは、YAMLやJSONファイルを生成するツールになります。

Apidocは、次のような特徴があります:

  • ソースコードにdocstring形式でコメントを記述するだけで、APIドキュメントが生成できる
  • Markdown形式で説明文を記述できる
  • APIのパラメータ、リクエスト形式、レスポンススキーマを記述できる
  • HTML、JSON、YAML形式のドキュメントを出力可能
  • ドキュメントのテーマをカスタマイズできる
  • Node.js製であるため、JavaScriptエコシステムとの親和性が高い

REST APIの開発において、API仕様と実装を同期するための有用なツールです。

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の知識が必要
  • バージョン管理が厳密ではない
button

そこで、よりAPIを作成して、管理するために、Apidogという完璧なAPI管理ソフトを使用することがおすすめです。Apidogを使用すると、手動でコードを書く必要がなくなり、直感的なGUIでAPIドキュメントを設計したり、APIを作成したりすることができます。それに、Apidogを使用して作成したドキュメントは、誰かにとっても非常に読みやすくなります。

APIドキュメント

また、ApidogはApidocのファイル、SwaggerのYAMLファイル及びJSONファイルからのインポートをサポートしています。APIをApidogに移行したい場合は、非常に簡単になります。

apidocをApidogに移行

Apidocで欠けているAPIのバージョンコントロール機能も、Apidogで非常に充実しています。Apidogのバージョンのコントロール機能を導入すると、異なるバージョンのAPIの変更点を表示することができるので、開発者は需要に応じて異なるバージョンを選択できますし、各バージョンの違いと変更をいち早く把握することもできます。

Apidogのバージョンコントロール機能
button

Apidogのニュースレターを購読する

今すぐ購読すると、いつでもApidogから更新情報と最新観点を手に入れることができます。