Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
805
Help us understand the problem. What is going on with this article?
@horimislime

REST APIドキュメント作成ツールはapiary.ioが決定版かもしれない

More than 5 years have passed since last update.

背景

これまでずっとREST APIドキュメントをwiki上で管理していて、重たいページ上で特殊記法使ったり、スタイルの調整に時間を取られるのが辛かった。そこで良さげなドキュメントツールを色々調べてたんだけど、最終的にapiary.ioが一番良さそうという結論になってきた。

このサービスの主な特徴。

  • markdown記法でAPIドキュメントを記述できる
  • ドキュメントの生成と同時にAPIのモックサーバを用意してくれる
  • サインアップから5分くらいあればドキュメント公開できる。ドキュメントのホスト先を気にしなくてもいい。

特にドキュメントと一緒にモックを作ってくれるのは他にはないポイントでかなり便利。

使ってみる

サインアップはGithubアカウントで http://apiary.io から。ログインしたら↓のようなサンプルのAPIドキュメントが用意されていて、ページ上のエディタですぐに弄って見た目をプレビューできる。

Screen Shot 0026-05-28 at 21.01.37.png

ドキュメントの記述はMarkdownライクな記法が使える。試しに1個APIを追加してみる。

# ユーザ情報API
## ユーザ情報へのアクセス [/user/{id}]

### ユーザ情報を取得する [GET]
+ Response 200 (application/json)

        {
          "nickname": "horimislime",
          "livetown": "tokyo"
        }

H1で一つのAPIグループを定義して、H2でそのAPIに属するエンドポイントを記述する。更にH3でエンドポイントがサポートしているHTTPメソッド毎のレスポンス例が書ける。上の例だと/user/{id}へのGETリクエストがstatus 200の場合に返ってくるjsonのbodyを記述している。

これだけ書いて保存すれば、即座にAPIドキュメントがグローバル公開される。
horimislimeのてすと API—by apiary.io

更に便利なことに、 ここで書いたリクエストやレスポンス形式を元にAPIのモックサーバまで生成してくれる!上の例だと http://horimislime.apiary-mock.com/user/{任意のID} にリクエストを飛ばせば定義しておいたサンプルレスポンスが返ってくる。

Screen Shot 0026-05-28 at 21.21.54.png

わざわざcurlとか叩かなくても、ドキュメントページ上のTry Itからリクエストを投げてレスポンスを確認することもできる。便利!

Screen Shot 0026-05-28 at 21.25.18.png

おわり

使ってみた印象、サインアップしてすぐ使えるのが楽で、しかもmarkdownベースな記法ですんなり書けるのがとにかく大きいと思った。チーム開発現場で新しいツール入れる時、導入とか学習のコストが悩みの種だけどこれなら入れる敷居も高くない気がする。

モックの自動生成も魅力的で、サーバサイドのAPI実装がなかなか進まない時クライアント側がAPI待ち状態になって申し訳ない感じになるけど、apiaryで書いておけば仕様決めてドキュメント渡すと同時にモックでテスト進めてもらえるから効率良さそう。

805
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
805
Help us understand the problem. What is going on with this article?