2023 追記

2023 年現在では、以下の文章では採用を見送っている OpenAPI を使えば OK という雰囲気です。

Web APIの設計

作者:Arnaud Lauret
翔泳社

Amazon

TL; DR

ドキュメント生成にはkevinrenskers/raml2htmlを使った
ドキュメントはRAML - RESTful API modeling languageで書いた
- RAMLにはJSON SchemaとJSONを記載できる
APIで返ってくるJSONはRailsアプリのrequest specでJSON Schemaを使ってテストした
JSON Schemaはr7kamura/json_worldで生成した
ドキュメントに載せる例示のJSONもJSON Schemaからgin0606/screijiを使って生成した
上記の方法だとリクエストパラメタとドキュメントの整合性を担保できないので、可能ならRAMLを使わず、全てJSON Schemaで書いたほうが検証しやすそう

使ってるツールとかだいたいRuby製だけど、最終的にjsonに吐き出したりしてるから他の言語のWAFでも使える気がする。

背景

以下を実施したプロジェクトの都合上、APIの実装でクライアントアプリの開発を止められない
- プロジェクト開始からクライアントアプリ開発が本格的に始まるまでの2週間ほどで、全てのAPIエンドポイントの定義と、mockでJSONを返すようにしたかった
クライアントアプリ開発が始まる段階で一通りのAPIドキュメントの提供したかった
過去に経験したプロジェクトで正しい情報が載っていないAPIドキュメントに苦しめられた経験があり、なるべくドキュメントと実装の整合性を保てる状態にしたかった
- 今回はサーバーサイド開発だったが、以前はクライアントアプリ開発メインだったので、そういう問題が起こる諸々の都合を把握したり、解決したりする方法を探りたかった。
  - あとサーバーサイド開発初挑戦で、インフラとか整うまで暇を持て余していた。

他にも色々あったり記憶が歪められてる気もするけど、だいたいはこんなもんだと思う。

技術選定

ドキュメントフォーマット

以上の5つが割りと使われてそうなフォーマットに上がった。

最終的にはRAMLを使うことにしたんだけど、以下が選定理由。

autodoc

rspecからドキュメント生成するやつ。

リクエストパラメタとか諸々テストしつつ、それを元にドキュメント生成出来るので、大分良さそうという感想だったんだけど、実装よりも先にドキュメント用意したいという感じだったので見送った。

次が諸々の不都合が無いRailsプロジェクトでもautodocは使わないで、json_worldとr7kamura/rack-json_schemaでどうにかすると思う。社内の別プロジェクトでScalaやGoが使われているのもあって、特定の言語やWAFに依存しすぎるの良くないという感じ。

JSON Schema

単体のJSON定義するくらいなら出来なくもないけど、記法を覚えるコストが高くて、これで全てを書くのは無しだという感じになった。

users.jsonをuser.jsonとかreference使って書く方法がどう頑張っても分からなくて、gin0606/schaiというgemを作ったりした。 schaiはプロジェクト中盤まで現役で使ってたけど、json_worldに移行して、レスポンスのJSONとJSON Schemaをjson_worldで生成するようになった。

なんで最初からjson_worldを使わなかったんだって感じだけど、当時はダメやんって思うことが何かあった気がするんだけど覚えてない。

サーバーがRubyでJSON Schema使うならjson_world使おうって感じ。

API Blueprint

Markdown書いてAPIドキュメントとMockサーバー建てられるやつ。

記憶が曖昧なんだけど、JSONとJSON Schemaを記載できる。

Apiary — Homeというサービスがあって、githubにドキュメント置いて、それからドキュメントとかMockサーバーとか作ってくれる。

Apiaryというサービス（会社）で使ってるし、直近でメンテされなくなる可能性とか低そうって思って、最初はAPI Blueprint導入してた。

Mockサーバー建ててくれるので、やりたいことに合致していて、ドキュメントに記載したJSON Schemaを元にnogates/vigiaとかcybertk/abaoを使ってドキュメントをJSON Schemaとの検証含めてテスト出来るかと思ったんだけど、出来なかったし、そんな書きやすくもなかったからやめた。

RAML

最終的に落ち着いたやつ。

http://raml.org/ 見れば分かるけどyaml書いてくやつ。

チャットワークAPIドキュメントで使われてる。

API Blueprintに比べて、APIのエンドポイントをyamlでツリーみたいに書いていけるので、だいぶ良かった。

説明とかが長いAPIあると、その下のエンドポイント書きづらいという問題もあるんだけど、ファイルを分けて書けたはずなので、そんな大きな問題にならないはず。

API Blueprintを止めた時点で、ドキュメントをそのまま使ってAPIとドキュメントの整合性を保とうという甘い考えを捨てて、レスポンスの整合性はrspecでjson schema使って検証しようという感じになった。ドキュメントをそのまま使ってAPIとドキュメントの整合性保てないなら、API BlueprintよりもRAMLのほうが断然書きやすいので、最終的にRAMLを使うことになった。

Swagger

なんか巨大すぎるしジャバやんみたいな雑な理由で全然調べずに止めた気がする。

雑すぎるので次API開発する機会あったらちゃんと調べたい。

ドキュメント生成

生成と言っても、RAMLなので結局手書きでAPIのドキュメントを書いてくことになる。

↓こんな感じのYAMLを書いていく。

schemas:
  - User: !include schemata/user.json

traits:
  - client_credentials:
      usage: Client Credentials Grantでアクセス可能なAPIに指定する
      headers:
        Authorization:
          description: OAuth 2.0 アクセストークン [Client Credentials Grant](http://openid-foundation-japan.github.io/rfc6749.ja.html#grant-client)
          type: string
          required: true
          example: "Bearer ACCESS_TOKEN"

  - resource_owner_password_credentials:
      usage: Resource Owner Password Credentials Grantでアクセス可能なAPIに指定する
      headers:
        Authorization:
          description: OAuth 2.0 アクセストークン [Resource Owner Password Credentials Grant](http://openid-foundation-japan.github.io/rfc6749.ja.html#grant-password)
          type: string
          required: true
          example: "Bearer ACCESS_TOKEN"

/users:
  displayName: ユーザー関連API
  post:
    is: [client_credentials]
    description: ユーザー登録
    body:
      application/x-www-form-urlencoded:
        formParameters:
          user[screen_name]:
            description: アカウント名（重複付加）
            required: true
            type: string
            example: yamada
          user[password]:
            description: パスワード
            required: true
            type: string
          user[password_confirmation]:
            description: パスワード確認
            required: true
            type: string
    responses:
      201:
        body:
          application/json:
            schema: User
            example: !include screiji/user.json
  /{user_id}:
    uriParameters:
      user_id:
        type: integer
    get:
      is: [client_credentials]
      description: ユーザー情報取得
      responses:
        200:
          body:
            application/json:
              schema: User
              example: !include screiji/user.json
    patch:
      is: [resource_owner_password_credentials]
      description: ユーザー情報更新
      body:
        application/x-www-form-urlencoded:
          formParameters:
            user[screen_name]:
              description: アカウント名（重複付加）
              required: false
              type: string
              example: yamada
      responses:
        200:
          body:
            application/json:
              schema: User
              example: !include screiji/user.json
    delete:
      is: [resource_owner_password_credentials]
      description: ユーザー削除
      responses:
        204:

schema: Userとかexample: !include screiji/user.jsonも手動で生成していて、app/resources/api/resources以下に存在するjson_worldで書いたクラスのJSON Schemaをファイルに書きだして、screijiでexampleのJSONをファイルに書き出すみたいなことをやった。

やってるrake task https://gist.github.com/gin0606/55bed5902fe820914c5b

更新忘れを防ぐためのテスト書いたりもしたけど、大分ダサい。

ドキュメント閲覧

module Api
  class DocController < ApplicationController
    def doc
      render html: raml2html, content_type: "text/html"
    end

    private
    def raml2html
      `#{Rails.root}/node_modules/raml2html/bin/raml2html -i #{Rails.root}/docs/api.raml`.html_safe
    end
  end
end

こんなようなことをしてる。

色々と手動でやっててダサいので、asset pipelineでerbなどでRAMLの元になるやつ書いて、その中でJSON Schema埋め込んで、HTML生成して描写するみたいなこと出来ればよかったんだけど、gemが無い＆asset pipeline全く分からんという感じで諦めた。

そんな感じで、TL; DRに全て書いてあるから他に特に書くことに気付き、JSON Schemaで全て済ませましょうねって感じ。

社内の別プロジェクトではScalaやGoが使われているので、言語やFrameworkが変わってもそこら辺のノウハウが使えることを考えるとJSON Schemaが良いのかなと思う。

Rails以外だとJSON Schemaを上手いこと生成してくれるツールが有るのか分からないけど、無かったらjson_world使っても良いと思う。簡単なDSLでJSON Schema生成出来るし、json吐き出せば各言語にValidatorあると思う。

gin0606/schaiはJSON Schemaの面倒くさいの色々と省いて生成してくれる。RAML使って色々やったプロジェクトでやった限りでは使い物になるんだけど、対応してないJSON Schemaのキーワードとかも多いし、Ruby学習の一環で書いたのもあってコードの品質も糞低い。使い物になるようにするなら1から書き直したほうが良さそうという感じ。

gin0606/screijiは、JSON Schemaから雑にJSONの例示を生成してくれるやつで、これは自分で作ったけど普通に便利だと思う。このプロジェクトでもまだ使っているけど、Ruby学習の一環で書いたのもあってコードの品質が低い。

2016/02/16 14:56 追記

Qiita API v2のJSON Schemaを公開しました - Qiita Blog

最近iOS アプリ開発リハビリがてらQiitaTeam見るやつ作ってて、これさっき読んだけど、JSON Schema使う理由とかドキュメント云々とかはこれに書いてあるとおりだと思う。

r7kamuraくんが書いたJSON Schemaとか周辺の文章にも大分影響されている自覚はある。

銀の人のメモ帳

僕が考えた最強のAPIドキュメント生成