Cloud Controller NG の API ドキュメント生成を試してみる

gistfile1.md

　このgistは Cloud Foundry Advent Calendar 2013 の23日目の記事です。今回はかなり軽めに。

　Cloud Controller NG (以下「CCng」) の document_api については，輪読会などでも何度か「壊れていて使えない」と言ってきましたが，この間再度試してみようと思ってREADMEを読んだら，気になる記述が。

API documentation

To genenerate the API documentation

bundle exec rspec spec/api/ --format RspecApiDocumentation::ApiFormatter
open doc/api/index.html

　これはもしや，CCngのissueで「作る」と言っていた新しいAPIドキュメント生成方法なのでは..。

　ということで，さっそくやってみました。

bundle exec rspec spec/api/ --format RspecApiDocumentation::ApiFormatter

Generating API Docs
  Private Domains
  GET /v2/private_domains
    * List all Private Domains
  POST /v2/private_domains
    * Create a domain owned by the given organization
  GET /v2/private_domains/:guid
    * Retrieve a Particular Private_domain
  DELETE /v2/private_domains/:guid
    * Delete a Particular Private_domain
  App Usage Events (experimental)
(..中略..)
  Apps
  PUT /v2/apps/:guid
    * Set a admin buildpack for an Application (by sending the name of an existing buildpack)
  GET /v2/apps/:guid
    * Retrieve a Particular App
  POST /v2/apps/
    * Creating an app
  DELETE /v2/apps/:guid
    * Delete a Particular App
  PUT /v2/apps/:guid
    * Set a custom buildpack URL for an Application
  GET /v2/apps
    * List all Apps
  Stable API warning system
    * tells the developer if the API specs change

Top 10 slowest examples (2.43 seconds, 48.5% of total time):
(..略..)

Top 2 slowest example groups:
(..略..)

Finished in 5.68 seconds
62 examples, 0 failures

　doc/api/ を見てみると，

ls doc/api

app_usage_events_(experimental)  index.html         service_brokers
apps                             index.json         serviceauthtokens
buildpacks_(experimental)        jobs               shared_domains
domains_(deprecated)             private_domains    spaces
events_(experimental)            quota_definitions  users

　確かになんかできてます。

　index.html をブラウザーで表示してみると，こんな感じの画面が出ました。

　試しに一つリンク先のページを開いてみると，こんな感じです。

　リクエストやレスポンスに関する情報や，サンプルなどもあります。

　ぱっと見た感じでは，なかなか役に立ちそうです。rspec_api_documentation というgemを使っているようなのですが，これをrequireしてrspecを所定の方法で記述すると，対象APIのドキュメントをrspecから生成してくれるみたいです。

　ただこれ，(当然のことながら)specが書かれているAPIしかドキュメント化してくれないようで，今のところ約60個のドキュメントしかありません。私が以前CCngの Web API 自動生成部にログを突っ込んで出力されたログからカウントしたところでは，CCngの Web API は全部で240くらいあるはずなので，1/4程度しかドキュメント化されていない計算になります。

　ちなみに，この方式のAPIドキュメント出力機能がリリースされたのは，README.mdのコミット履歴からみると，11/2のようです(前述の rspec_api_documentation gem は，もっと前から導入されていたようですが)。私がソースコード輪読会で「document_apiは壊れている」と言ったのは10/25なので，ぎりぎりセーフ(何が?)という感じでしょうか。

　それでは，今回はこの辺で。