(画像は API Blueprint の Web サイト より転載) GMO アドパートナーズ グループ CTO 室の M. Y.(DevOps ネタ担当)です。今回は、API 開発時に使って便利だったツールの話をします。 きっかけ 最近、私が担当している広告関係のプロダクトに、お客様向けに公開する API を新規追加することになりました。この API はお客様側のエンジニアが利用するため、API 仕様書を作る必要があります。 過去の社内事例では、Word ファイルで API 仕様書を作成して、配布していました。しかし、Word ファイルでは差分を確認しづらいので、API 仕様自体のバージョン管理が大変です。そこで、今回は API 仕様書から配布用の HTML を自動生成することにしました。 API 仕様書を自動生成する技術としては Swagger が有名ですが、今回のプロダクトでは AP
APIを作る機会が増えてきている 例えばマイクロサービス間はAPIでやりとりすることが多い。 外部のサービスもだいたいAPIでやりとりする。 社内APIもいくつかあるが、いざ使おうとなるとどんなリクエストを送るべきなのか、またどんなリクエストが返ってくるのかを調べるのが面倒。 API ドキュメントを書くのは大変 フォーマットは? Markdown? HTML? Text? エンジニア間で書き方がバラバラにならない? そのドキュメントの内容は今も正しい? そもそも書くのが面倒… ということで、いい感じのAPIドキュメントツールがほしい API ドキュメントツールに求めること その1 ドキュメントが書きやすい ドキュメントが読みやすい ドキュメントがGitで管理しやすい リクエスト情報、レスポンス情報が見やすい curlですぐに試せるようにサンプルがほしい ドキュメントとコードに乖離がないよう
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く