f:id:toranoana-lab:20211206094517p:plain

こんにちは、とらのあな通販のマーケティングチームでスクラムマスターを担当している大場です。

本記事は虎の穴ラボ Advent Calendar 2021 - Qiita 6日目の記事です。

5日目はY.I.さんの『Anime.js + SVG で画像をヌルヌル動かす！』でした。 toranoana-lab.hatenablog.com

明日の7日目は服部さんによる『VSCode Remote Container 』に関する記事の投稿を予定しています。

はじめに

新規でAPIサーバーを構築する際は皆さんどうしているでしょうか？よくある流れとしては、開発前に設計書を作成し、サーバーサイドとフロントサイドでお互いに認識合わせを行い、その設計内容に基づいて構築することが多いと思います。

しかし、実際には作成した設計書と実際の挙動で差異が発生したり、途中で急な仕様変更が加わった際など、ドキュメントには反映されずにAPIの挙動だけが変わった！なんてパターンもありそうです。

今回紹介する Swagger → API Gatewayを構築する流れであれば、Swaggerで作成したAPI定義を元にAPIサーバを構築できるので、『設計書↔実際の動作』での差異の発生を抑止することができます。

それでは、Swaggerについてかんたんに紹介したあと、APIを構築する具体的な手順を紹介していきます！

Swaggerとは

Swaggerは、API構築を簡素化するために作られたオープンソースのツール群です。

Swaggerは幾つかのツールを備えており、代表格であるSwagger Hub は以下の機能がまとまったプラットフォームとなっています。

Swagger Editor　　：設計時に利用するエディタ
Swagger UI 　　　：仕様をHTML形式で表示するツール
Swagger Codegen ：スタブを自動生成するツール

また、Swaggerでは以下のOpenAPI仕様(Swagger Spec)に基づき、フォーマットはJSONもしくはYAML形式でドキュメントを作成する必要があります。 swagger.io

JSON Schemaで既にAPI仕様を記述している方はとっつきやすいですが、JSON Schemaと完全に互換性があるわけではない為、 OpenAPI仕様の独自の書式に慣れていないとスムーズに記述することは少し難しいです。

しかし、仕様に則って記述することで一定の品質を確保できるといったメリットがあり、 Swaggerからサーバーを構築するという開発手順を守れた場合は、きちんとドキュメント情報が残るので属人化の防止に繋がります。

Swaggerの記述方法について

記述方法は、大きく以下の3つが挙げられます。

Swagger Editor(Web)を使う
VSCodeの拡張機能を使う
Swagger Editor(ローカル環境)を使う

それぞれの利用ケースとしては、以下の通りです。

試しにどんなものか触ってみる　→　1. Swagger Editor(Web)を使う
本格的にSwaggerを書いていく　→　2. VSCodeの拡張機能を使う
仕様が固まってチームに展開する→　3. Swagger Editor(ローカル環境)を使う

また、Swaggerの導入が決まった場合にチーム全体開発において向いているのは以下の通りです。

チームでVSCodeでの開発を推奨　　　→　2. VSCodeの拡張機能を使う
チームでVSCode以外での開発を推奨　→　3. Swagger Editor(ローカル環境)を使う

上記に加えて、Swagger Specを共有するという運用が好ましいです。利用ケースを断定してしましたがチームにSwaggerを導入しようと考えている方は、自身で一通り触ってみることをオススメします。

Swagger + API Gateway + lambda でのサーバ構築

ここから、以下の流れで実際の構築手順を紹介していきます！

Swagger Viewer(VSCodeの拡張機能) でSwagger Spec の作成
API Gatewayから呼び出す Lambda の作成
Swagger Spec を元に API Gateway を作成

Swagger Viewer

まずは、簡単にSwagger Viewerのインストール方法と起動方法を紹介します。 VSCodeの拡張機能は利用しないという方は、少し下の方に記述している『Swagger Spec （サンプル）』を控えてLambdaの手順へお進みください。

インストール

VSCode の Market Place から『Swagger Viewer』を検索してインストールします。 f:id:toranoana-lab:20211202095827p:plain

起動

コマンドパレットから『Preview Swagger』で起動できます。 f:id:toranoana-lab:20211202123112p:plain

以下のように、リアルタイムに出力結果を確認しながらSwaggerを記述できます。 Swagger Editorと違い入力補完が効くのでSwagger Editorよりも効率的です。

f:id:toranoana-lab:20211202123157p:plain

Swagger Spec （サンプル）

さくっと試しに使ってみたいという方は、コピペしてご利用ください。

openapi: "3.0.3"

info:
  title: "TEST"
  version: "1.0.0"

paths:
  "/message":
    get:
      responses:
        "200":
          description: "GET TEST"
          content:
            application/json:
              schema:
                type: string
                example: "Hello World !"

Lambda

API Gatewayから呼び出す関数としてLambdaを作成していきます。

Lambdaは、サーバーを構築することなくイベントをトリガーとして、任意のコードを実行できるサービスです。 https://aws.amazon.com/jp/lambda/

1.Lambda 関数の作成

Lambda から関数の作成を選択します。

2.関数の作成

以下の手順を踏むことで、' Hello from Lambda! 'を返すだけのLambda関数が作成されます。

一から作成をクリック
任意の関数名の入力
ランタイム Node.js 14.x
関数の作成をクリック

3.テスト実行

コードソースの『TEST』をクリック
テストイベントの作成(デフォルトのままで作成)
『実行』をクリック

HTTP Status Codeが200で、' Hello from Lambda! ' が返ってきたら成功です。 f:id:toranoana-lab:20211202133321p:plain

API Gateway

API の作成、公開、保守、モニタリング、保護が簡単に行えるAWSサービスです。 aws.amazon.com

以下3種類のAPIを作成することが可能です。

HTTP API　　　　： AWS Lambda等のサービスにおいて、低レイテンシーでコスト効率が高い
REST API　　　　： HTTP API よりも機能が豊富
WEBSOCKET API 　：クライアントとバックエンド間の双方向通信をサポート

今回はREST APIの形式で構築していきます。

1.API Gatewayの作成

API Gatewayの画面から『APIを作成』をクリック

2.REST APIを選択

APIタイプは、『REST API』のインポートをクリックします

3.Swaggerをインポート

プロトコルを選択で『REST』を選択
新しいAPIの作成で『Swagger あるいは Open API3からインポート』を選択
Swagger Specを貼り付け
『インポート』をクリック

注意

サンプルのSwagger Specを利用した方はインポートに失敗するはずです。失敗した原因は、model type で schemaを指定していた為です。

schemaの部分は実際に動作するlambdaの仕様の基づくので、schemaを指定することはできません。以下の記述を削除すると、今度は正しくインポートできると思います。

                type: string
                example: "Hello World !"

その他にも、yaml形式だと失敗するといったケースがあり、 JSON形式に変換してからインポートするといった対応が必要なのでご注意ください。

4.GETメソッドの定義

GETの『今すぐ設定』をクリック
結合タイプ『Lambda関数』
任意で関数名を入力
『保存』をクリック ※「API Gatewayに、Lambda関数を呼び出す権限を与えようとしています」という表示が出たら『OK』をクリック

5.テスト実行

『テスト⚡』をクリックします
クエリ文字列、ヘッダー、指定なしで『テスト』をクリック ※HTTP Status 200が返ってくる事が確認できます。
テスト実行

6.APIのデプロイ

『アクション』から『APIのデプロイ』を選択
新しいステージからステージ名を任意で入力
『デプロイ』をクリック
URLの呼び出し URL が表示されるので、定義したpathにアクセスしてみる。 ※サンプルを利用している場合は/messageへGETリクエスト

レスポンス結果が返ってきたら成功！！ f:id:toranoana-lab:20211202141327p:plain

おわりに

今回は新規作成時にSwaggerを利用する手順を紹介しましたが、後からAPIの仕様変更が発生した際でも、 APIのインポートから再度Swaggerを流し込むことで API Gatewayを更新することが可能です。

新規構築のシーンのみならず、API Gatewayを変更する際は必ずSwaggerを経由するという運用にすれば、ドキュメントと実際の挙動での差異を無くすことができますね。

また、今回はSwaggerとAPI Gatewayをセットで利用しましたが、Swaggerは単体でも利用できます。もし、この記事をきっかけにSwaggerを知った方は、Swaggerだけでも良いので利用を検討してみても良いかもしれません。

明日7日目は服部さんの記事を公開予定です！是非ご覧ください！！

P.S.

採用説明会 (2021/12/23)

■近日開催予定の採用説明会です！お申し込みはconnpassから！
yumenosora.connpass.com

採用情報

■募集職種
yumenosora.co.jp

カジュアル面談も随時開催中です

■お申し込みはこちら！
news.toranoana.jp

■ToraLab.fmスタートしました！

メンバーによるPodcastを配信中！
是非スキマ時間に聞いて頂けると嬉しいです。
anchor.fm

■Twitterもフォローしてくださいね！

ツイッターでも随時情報発信をしています
twitter.com

虎の穴開発室ブログ

虎の穴ラボ株式会社所属のエンジニアが書く技術ブログです

Swagger + API Gateway + lambda でAPI定義を流用したAPIサーバー構築

目次