なにがでるか

先日、SendGridのドキュメントに新しいAPIドキュメントが追加されました。元々、APIリファレンスに相当するドキュメントは存在していたのですが、 StopLight というサービスの機能を使ってより使いやすく整理した、といったところでしょうか。 入り口 新しいドキュメントの入り口はちょっとわかりづらくて、 ドキュメントのトップページ 上にある「 SendGrid API 」というリンクです。 主な特徴 次に、この新しいAPIドキュメントの特徴をまとめてみます。 リクエストとレスポンスがちゃんと定義された 今まで定義されてなかったのかよ、って感じですが、 これまで はリクエストについては概ね定義されていましたが、レスポンスはほとんど定義されていませんでした。レスポンスの例は載っていたので特に不都合はなかったのですが、ちゃんとした定義があるに越したことはありませんね。 Swagger(OAS)/RAMLによる定義が公開された StopLightの機能の一つですが、APIの定義全体がSwagger形式とRAML形式で公開されています。これがあると、 SendGridのAPIサーバのモックを作ってテストに利用 するといったことができるようになります。 APIドキュメントからリクエストのテストができるようになった これもStopLightの機能の一つのようですが、各エンドポイントのページの「 Try it out 」タブを選択するとドキュメントからAPIのリクエストを送信して結果確認ができます。使い方はとても簡単で、必要なパーミッションを持ったAPIキーをYOUR_API_KEYパラメータに設定、リクエストJSONをBodyに指定して「 SEND REQUEST 」ボタンを選択するだけです。 コード生成ができるようになった 「 Try it out 」でリクエストを送信すると、代表的な言語のコード生成ができるようになります。「 Code Generation 」から一通りのプログラミング言語およびコマンドのサンプルコードが確認できるので、サッとコピペして使えます。 PostmanにSwaggerの定義ファイルを喰わせてみる Swaggerの定義 が公