こんにちは。對馬です。
 

このたび、8月29日(火)にPOINT EDGEさんのコワーキングスペースにてAPIStudy #11が開催されました。

その様子を報告します。

 

 

第1部：LTタイム

MOONGIFT　中津川さんです。

中津川さんもまたまた2回目の登壇です。

前回はニフティクラウド mobile backendに関して、#5のときにお話しいただきました！

そのときの開催報告はこちらです。

 

今回は『APIドキュメントの光と闇』についての発表です。

 

 

ドキュメントの形式は、「システム連携型」、「静的HTML型」、「Wiki型」の3つとされています。今回はWiki型を省いた2つ形式についての光(メリット)と闇(デメリット)を紹介します。

 

システム連携型

コード+DSLでSwagger.jsonを生成し、それをコンバートしてHTMLドキュメントにしていきます。

 

メリット

• コードの近くにドキュメントを書ける
• メンテナンス容易
• 網羅性も担保される
  
  

デメリット

• ファイルサイズが大きい
• ドキュメントを書けば書くほどコード量は圧縮されていくので、コードの可読性が下がる
• プログラミングとドキュメントが区別しにくい
• 多言語対応が難しい

 

静的サイト型

開発ドキュメントを作るための静的サイトジェネレーターを使ったもので、静的HTMLを吐き出せるのでGithubにそのまま登録することができます。

 

メリット

• チュートリアルまで作りやすい
• 多言語対応しやすい
• 自由度が高い
  
  

デメリット

• 網羅性が低い
• メンテナンス工数が高い
• 多言語対応時の工数が高い(翻訳したときの変更された差分がわからないという翻訳問題。)

 

解決策

MkDocs+Swagger.json+スクリプト(Ruby)→Markdownファイルを生成。

さらにGetTextで多言語化とメンテナンス性を維持しています。

 

Squareの話

Square は、スマホやタブレットでカード決済を行うためのサービスです。

中津川さんはSquareのDevRelをサポートしており、Squareの場合についてもお話してくださいました。

 

Squareの場合、社内サービスはProtocol Buffersで実装しています。

Protocol Buffersで定義し、JavaでSwagger.jsonを出力、そのJSONをHTMLドキュメントに変換するという方式です。

さらに、出力されたSwagger.jsonをSwagger Codegen (Swagger公式のjava製コードジェネレーター)で利用すると、SDKを自動生成できるそうです！

 

 

第2部：ディスカッション

第2部ではテーマで分かれ、ディスカッションをしてもらいます。

 

今回のテーマは以下2つです。

• 網羅性とメンテナンス
• APIの情報集約

 

 

 

 

網羅性とメンテナンス

ドキュメントとコードの連携

ドキュメントとコードの階層を同じにしておけば、分けて記述しても見やすくなります。

APIのドキュメントをテストコードから作れたら理想。

ユーザーが使うAPIであれば、ユーザーが実際に活用する業務知識も取り入れていけるとより親切です。

 

メンテナンス性

ドキュメントは企業の顔になるので、本来誰が書くべきなのか？

コード担当とドキュメント担当を分ける場合は、情報連携をどのようにしていくかが重要です。

また、テスト・コード・ドキュメントの担当者が別なので、書き方に統一性がなくなることが課題です。

ベストなのは、ドキュメントのノウハウを勉強する機会があること！

 

多言語対応

多言語はコストがかかるので要注意です。

 

よいドキュメントの例

Stripe、Square、楽天、Yahoo、Herokuの5つが挙げられました。

ぜひお手本にしてみてはどうでしょうか！

 

APIの情報集約

情報集約の困るところ

• 海外の情報が見にくい。
• 期限切れ対策。
• 開発者ブログのエントリーが最新情報の場合もあるので、集約が必要です。

 

セキュリティに関しては脆弱性についてまとめることでその企業がセキュリティに強い！と認められるといったビジネス的価値がありました。

しかしAPIに関して情報をまとめたとしても、ビジネス的価値がある等のインセンティブが見いだせられていないのが現状です。

API集約サービスは既にあるので、お話を聞いてみたいという声が上がりました！

 

最終的にほしい情報

• 使い方が知りたい。
• ニュース系の情報がほしい。

 

感想

APIの共通認識がほしい。

→一般社団法人API協会　設立希望！

 

 

POINT EDGEさんから連絡

さいごに、今回会場を提供してくださったPOINT EDGEさんから、会場の紹介をしていただきました。

 

アクセスもよく綺麗なスペースで、何よりスタッフさんが大変親切でした。

詳細はこちらから。ぜひ利用してみてください！

 

おわりに

毎度お楽しみのグラレコがこちらです！

今回も素敵な仕上がりですね！いつもありがとうございます！

 

 

#11も無事に終了でき、大変嬉しく思います。

初参加の方からも満足したという感想をいただきました！

 

そしてついに！

APIStudyは次回で1周年を迎えます！

これもみな、参加者の皆様、歴代会場提供企業様、そして運営スタッフのおかげです！

ありがとうございます。

 

記念すべき#12は、GROOVE Xさんで開催されます。

ぜひ以下リンクよりお申込みいただければと思います。

 

 

宜しくお願いします！