Edited at

API Blueprintとその周辺ツール

More than 1 year has passed since last update.


APIを作る機会が増えてきている


  • 例えばマイクロサービス間はAPIでやりとりすることが多い。

  • 外部のサービスもだいたいAPIでやりとりする。

  • 社内APIもいくつかあるが、いざ使おうとなるとどんなリクエストを送るべきなのか、またどんなリクエストが返ってくるのかを調べるのが面倒。



API ドキュメントを書くのは大変


  • フォーマットは? Markdown? HTML? Text?

  • エンジニア間で書き方がバラバラにならない?

  • そのドキュメントの内容は今も正しい?

  • そもそも書くのが面倒…



ということで、いい感じのAPIドキュメントツールがほしい



API ドキュメントツールに求めること その1


  • ドキュメントが書きやすい

  • ドキュメントが読みやすい

  • ドキュメントがGitで管理しやすい

  • リクエスト情報、レスポンス情報が見やすい

  • curlですぐに試せるようにサンプルがほしい

  • ドキュメントとコードに乖離がないようにしたい


ここまでは一般的な要求。しかしAPIドキュメントにリクエスト/レスポンス情報の構造や型情報、ステータスコード、ヘッダー情報が書かれているともっと多くのことを望むようになる。



API ドキュメントツールに 求めること その2


  • APIドキュメント内のリクエスト情報とレスポンス情報を用いてプログラムのバリデートしたい

  • APIドキュメントからプログラムを自動生成したい

  • プログラムからAPIドキュメントを自動生成したい

  • APIドキュメントからモックサーバーをたちあげたい



有名なAPI ドキュメント ツール


  • Swagger

  • API Blueprint

  • JSON Schema

  • RAML



Swagger


  • SwaggerはREST APIの記述に関する仕様とそれら周辺のツールを指す

  • Open API InitiativeというREST APIの記述標準化を進める団体があり、その標準フォーマットがSwagger

  • YAML/JSONで記述する。

  • もっとも大きく、そして高機能

  • 比較的読みやすい



API Blueprint


  • Web APIの仕様をMarkdown拡張形式で記述する

  • 人が読み書きしやすいフォーマット

  • もともとはApiaryというサービスで使用するフォーマットで、それが普及した



JSON Schema


  • JSONの構造(schema)や各要素の型を定義するフォーマット

  • JSON/YAMLで記述する

  • JSON Hyper-Schemaという仕様があり、Web APIの仕様が定義できる

  • (そのままでは)API仕様書としては読みにくい



RAML


  • YAMLを使ってAPI仕様を記述する

  • 他のツールに比べて後発

  • 他のAPIドキュメントよりは読みやすい

  • Swaggerに似ている



今回紹介するのはAPI Blueprintとその周辺ツール



API Blueprintの例



Markdownでもいいけど、もうちょっとかっこいいAPIドキュメントがほしい



aglio



api-blueprint-previewプラグイン



できればAPIドキュメントはみんながみれるサーバーにおきたい。でもそれを管理するの面倒…



Apiary(エイピエリ)



モックサーバー、ローカルでもちょっとほしい



api-mock

% api-mock user_api.md

info: Enabled Cross-Origin-Resource-Sharing (CORS)
info: Allow-Origin: *
info: Allow-Methods: GET, PUT, POST, PATCH, DELETE, TRACE, OPTIONS
info: Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization, Referer, Prefer
info: Listening on port 3000

% curl http://localhost:3000/users/1
{
"name" : "John",
"age" : 20,
"admin" : true
}



でもAPIドキュメントをしっかり書いても、しばらくしたら実装と乖離してしまう恐れが…



Dredd


  • https://github.com/apiaryio/dredd

  • API Blueprintをもとに実装をテストしてくれる

  • .dredd.ymlにAPIエンドポイントを設定

  • dreddはそのエンドポイントに対してAPI Blueprintで定義されたAPIリクエストをなげ、レスポンス内容がAPI Blueprintで定義された内容と合っているかをテスト



まとめ


  • API Blueprintを使えば、人が読み書きしやすいAPIドキュメントが簡単につくれる。

  • aglioを使えばさらに見やすいドキュメントになる。

  • 書く場合はAtomプラグインを使うと書きやすい。

  • Swaggerのように高機能でないが、さくっとドキュメントを作りたい場合はおすすめです。