Swaggerについて

2025/01/27に公開

状況

  • 初めてフロントエンドとバックエンドの異なるアプリケーションの設計に携わることに
  • バックエンドがNestJS, フロントエンドがNext.js, 共通モジュールがTypeScriptのアプリケーションとのこと
  • 開発にあたり、「Swagger」を利用していたため調べてみた

内容

Swaggerとは?

  • Swaggerは、RESTful APIを設計、構築、記述、テスト、および管理するためのツールセット
  • 現在では OpenAPI Specification (OAS) の一部として知られており、APIドキュメントを標準化して作成することが目的

Swaggerは特に以下の場面で役立つ:

  1. API設計:APIの仕様を定義しやすくする
  2. APIドキュメントの生成:わかりやすいインターフェース(UI)でAPIの動作を確認できる
  3. テストと検証:Swagger UIを使ってAPIの動作をインタラクティブに確認し、テストする
  4. 開発者間のコミュニケーション:標準化されたドキュメントで、開発者やチーム間の理解を深める

どんな時に使いますか?

  • APIのドキュメントを自動生成したい場合

    • APIエンドポイント、リクエスト/レスポンスの構造を記述し、即座にUIに変換できる
  • APIの設計フェーズ

    • チームでAPIの仕様を議論し、OpenAPI形式で記述する
    • これにより、フロントエンドとバックエンドの開発を並行して進めやすくなる
  • APIの動作確認やテスト

    • Swagger UIを通じて、エンドポイントの動作をブラウザで確認でき、手軽にリクエストを送信できる
  • 第三者にAPIを公開する場合

    • 外部開発者が使用するAPIを提供する際、Swaggerを利用してドキュメント化することで、利用者の学習コストを下げることができる

似たようなアプリケーション

  • Postman:
    • 主にAPIのテストや動作確認をするためのツール
    • Swaggerとは異なり、設計やドキュメント生成の機能は弱い

https://www.postman.com/

  • API Blueprint:
    • Swaggerと似たAPI設計・ドキュメント化ツール
    • Markdown形式で記述できるのが特徴

https://apiblueprint.org/

  • RAML (RESTful API Modeling Language):
    • Swaggerの競合となるAPI仕様言語。特にモジュール化に強みがある

https://raml.org/

  • Redoc:
    • Swagger/OpenAPI仕様に基づいたAPIドキュメントを、カスタマイズ可能な静的HTMLページとして提供

https://github.com/Redocly/redoc


具体的な使い方

1. Swagger Editorでの設計

例: 簡単なAPIの定義

openapi: 3.0.0
info:
  title: Sample API
  version: "1.0.0"
paths:
  /users:
    get:
      summary: Get list of users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

2. Swagger UIでの可視化

Swagger Editorで作成した仕様は、Swagger UIで以下のように表示される:

  • エンドポイントごとの説明
  • 必要なリクエストパラメータ
  • サンプルレスポンス
  • 実際に「Try it out」ボタンでAPIを呼び出せる

3. コード生成

Swagger Codegenを使用すると、以下のようなサーバーやクライアントのコードを自動生成できる:

swagger-codegen generate -i api-spec.yaml -l ruby -o ./output
  • -i:API仕様ファイル
  • -l:生成する言語(例:Ruby, Python, Javaなど)
  • -o:出力先フォルダ

4. APIドキュメントの公開

  • Swagger UIをプロジェクトに組み込み、開発者向けにドキュメントをホスティング
  • Railsアプリケーションでは、swagger-docsrswagを利用して簡単に統合できます。

まとめ

  • Swaggerは、RESTful APIの設計から公開、テストまでを一貫してサポートする強力なツール
  • 特にドキュメントの自動生成と標準化に優れており、効率的なAPI開発に欠かせない存在
  • 他のツールとも組み合わせて使える

所見

  • googleドキュメント cloneの次のステップとも関係ありそうなのでこちらも使ってみながら学習してまいりたい

Discussion