Zenn
😎

OpenAPIでREST APIを型安全にする調査

2023/07/30に公開
Swagger
OpenAPI
tech

✅ 目的

自社で技術選定できる場合、GraphQL や tRPC など API 通信が型安全になるような技術選定をしています。

受託案件の現場によっては上記のように、API 通信の型安全性が確保されてないケースによく遭遇します。

この記事では、OpenAPI を用いた型安全性の確保について調査しまとめます。

✅ 対象読者

  • REST API で開発しているが、API 通信が型安全じゃなくて悩んでいる人
  • いつの間にか API 仕様が変更され、フロントエンドが追従できずにデグレするのがもうウンザリな人
  • Swagger は使っているけど、コードの自動生成まではできてない人
  • OpenAPI・Swagger とかちょっと聞いたことあるけどよく知らない人
  • OpenAPI・Swagger なにそれ美味しいの？な人

✅ OpenAPI

HTTP API のための標準化された仕様言語です。
JSON または YAML 形式で記述されます。
定義した API 仕様からコードを生成したり、テストケースを記述できます。

ペットの一覧を取得する API の例
{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

公式ドキュメント
https://www.openapis.org/

✅ Swagger

API の設計とドキュメント化を支援するツールです。

公式ドキュメント
https://swagger.io/

以下の３種類のツールを提供しています。

  • Swagger UI
  • Swagger Editor
  • Swagger Codegen

１つずつ解説します。

◼️ Swagger UI

API リソースを視覚化し、操作できます。
OpenAPI 仕様を元に自動生成されます。
開発メンバー間で API の設計や機能実装の際に意思疎通できます。

リソースとそれに対する API 操作が一覧されます。
Image from Gyazo

各 API 操作では、API に関する説明とリクエストとレスポンスの形式（正常系・異常系）などが定義できます。
Image from Gyazo

◼️ Swagger Editor

API の設計と記述、ドキュメント化を支援するツールです。

左側ペインがエディタとなっていて、編集内容が即座に右側ペインの UI に反映されます。
サンプルのエディタ
Image from Gyazo

◼️ Swagger Codegen

Swagger Editor で作成した API 仕様を元に、API サーバーのスタブやクライアントコードを自動生成します。

自動生成により、API 通信が型安全になります。
（動的型付け言語でどこまで型安全にできるかは未調査）

多くのフレームワーク・プログラミング言語に対応しています。

自動生成するには swagger-codegen のダウンロードが必要です。
swagger-codegen の GitHub
（この記事では詳細な使い方の説明は省きます）

✅ openapi-generator

Swagger Codegen と同じ立ち位置です。
cli ツールをインストールして、OpenAPI 仕様からコード生成します。

公式ドキュメント
https://openapi-generator.tech/

対応言語は以下の URL で確認できます。
https://openapi-generator.tech/docs/generators

✅ Spotlight Studio

Swagger の上位互換です。

Swagger では API 仕様を JSON または YAML 形式で記述する必要があります。

Spotlight Studio では、リッチな GUI で API を設計できます。
内部的に API 仕様(JSON/YAML ファイル)を自動生成します。

GitHub と連携し、定義した API 仕様を push することができます。


公式ドキュメント
https://stoplight.io/solutions

✅ まとめ

  • API 仕様は OpenAPI という標準化された仕様言語で定義できる
  • Swagger や Spotlight Studio などの支援ツールで API を設計・ドキュメント化できる
  • 作成した OpenAPI 仕様からバックエンド・フロントエンドのコードを自動生成できる
  • コードの自動生成により API 通信が型安全になる

✅ 感想

個人的には、Spotlight Studio で API 設計して、OpenAPI 仕様からコード生成する流れが開発者体験良さそうかなと感じました。

具体的な使い方は別途調査して、記事が書けたらこの記事にもリンクします。

GitHubで編集を提案

Discussion