法人のお客さま
お問い合わせ
ビジネスブログ

ネイティブアプリ1年生が感動したSwaggerの機能と使い方

著者写真

クラウドテクノロジーブログ
宮下 美里

2024年12月24日掲載

キービジュアル

初めまして！ネイティブアプリエンジニア1年生の宮下です。

ソフトバンクアドベントカレンダー2024、クリスマスイブの24日目を担当します。

初めてAPIの開発をした際にSwaggerに触れ、その使いやすさとわかりやすさに感動しました！SwaggerはAPIキュメントを自動で生成し、グラフィカルなインターフェースを通じて直感的に理解できます。これにより、自作のコードの動作確認やAPIのレスポンス確認をすぐに行うことができ、開発が非常にスムーズに進みます。

今回は、私が感動したAPI開発で大活躍するSwaggerについて、初心者目線でわかりやすく解説します。DockerによるSwagger環境構築、Swagger Codegenを使ったコード自動生成や、実際にAPIリクエストを送信してレスポンスを確認する方法も紹介します。

 

目次

  • この記事の対象者：API開発初心者、API仕様書の作成に時間をかけたくない開発者

1.Swaggerとは？

SwaggerはAPI設計やドキュメント作成を効率化するツールセットです。RESTful APIの開発プロセスを簡素化するために使用されます。Swaggerは、APIの仕様を記述するためのフォーマットであるOpenAPI Specification（OAS）を基盤としており、この仕様によりAPIの動作を標準化された形式で表現できます。

Swaggerを使えば以下のようなことができます。

  • API仕様書の自動生成：YAML形式で記述した仕様からドキュメントを生成してくれます。
  • インタラクティブなUI：ブラウザ上でAPIエンドポイントやレスポンス形式を確認できます。
  • コード生成：クライアントコードやサーバースタブを自動生成できます。

[Sswagger導入のメリット]

  • バックエンドとの連携がスムーズになります。
  • ドキュメントの作成を効率化し作業時間を短縮できます。
  • 開発者が同じ仕様書を見るため、認識齟齬を防ぐことができます。

2. Swaggerの主な機能

[Swagger UI]

Swagger UIは、APIドキュメントを視覚的に表示し、インタラクティブに操作できるツールです。これにより、開発者や利用者はAPIのエンドポイントを簡単に試すことができます。

  • APIドキュメントの視覚化: Swagger UIは、API仕様書をHTML形式で表示し、エンドポイントやパラメータをわかりやすく示します。これにより、技術的な知識が少ない人でもAPIの構造を理解しやすくなります。

  • テスト: ユーザーはSwagger UI上で直接APIリクエストを送信し、そのレスポンスを確認できます。これにより、開発中のAPIの動作確認が容易になり、不具合の早期発見が可能です。

[Swagger Editor]

Swagger Editorは、API仕様書をYAMLまたはJSON形式で作成・編集できるオンラインツールです。リアルタイムで構文チェックが行われるため、正確な仕様書作成が可能です。

  • YAML/JSON形式での仕様書作成: Swagger Editorでは、YAMLやJSON形式でAPI仕様書を書くことができます。これらの形式は人間にも読みやすく、構造化されたデータ表現が可能です。

  • リアルタイム構文チェック: 編集中に構文エラーがある場合は即座にフィードバックが表示されるため、ミスを未然に防ぐことができます。

[Swagger Codegen]

Swagger Codegenは、API仕様書からサーバースタブを自動生成するツールです。多くのプログラミング言語とフレームワークに対応しており、開発効率を大幅に向上させます。

  • 自動コード生成: API仕様書から対応するコードを自動生成することで、手動によるコーディング作業を削減します。これにより、開発時間とコストの削減につながります。

  • 多言語対応: Java, Python, JavaScriptなど、多様なプログラミング言語でコード生成が可能です。プロジェクトごとに適した言語やフレームワークを選択できます。

3.DockerでSwagger環境を構築する

Dockerを使ってSwagger環境を構築する方法を解説していきます。この手順で簡単にローカル環境でSwaggerを利用できます。

ステップ0：事前準備

DockerとDocker Composeがインストールされていることを確認してください。

ステップ1：Docker Composeファイルの作成

ご自身のプロジェクトディレクトリに’docker-compose.yml’という名前のファイルを作成し、以下のような内容を記載してください。

 

services:
  swagger-editor: #Swagger Editorサービス
    image: swaggerapi/swagger-editor  #Dockerのイメージ名
    container_name: "swagger-editor"  #コンテナ名
    ports:
      - "8001:8080"  #ローカルポート8001からコンテナ内8080へマッピング
  swagger-ui: #Swagger UIサービス
    image: swaggerapi/swagger-ui  #Dockerのイメージ名
    container_name: "swagger-ui"  #コンテナ名
    ports:
      - "8002:8080"  #ローカルポート8002からコンテナ内8080へマッピング
    volumes: 
      - ./api/openapi.yaml:/openapi.yaml #ローカルのOpenAPI仕様書をコンテナ内にマウント
    environment:
      SWAGGER_JSON: /openapi.yaml #Swagger UIで読み込む仕様書のパス
  mock-server:  #モックサーバー
    image: stoplight/prism:4
    container_name: "mock-server"
    ports:
      - "8003:4010"
    command: mock -h 0.0.0.0 /openapi.yaml
    volumes:
      - ./api/openapi.yaml:/openapi.yaml

ステップ2：OpenAPI仕様書の準備

次に、’./api/openapi.yaml’というディレクトリに、以下のようなOpenAPI仕様書（YAML形式）を作成します。

 

openapi: 3.0.0  # OpenAPIのバージョン指定
info:
  title: Swagger Sample # APIのタイトル
  version: 1.0.0  # バージョン情報
servers:
  - url: http://localhost:8003
paths:
  /helloSwagger:  # エンドポイント
    get:  # HTTPメソッド
      summary:  Sample API  # APIの概要
      responses:
        '200':  # ステータスコード200の場合のレスポンス定義
          description:  This is swagger sample  # レスポンス内容の説明
          content:
            application/json: # レスポンス形式(JSON)
              schema:
                type: object  #配列内オブジェクトの定義
                properties:
                  message:
                    type: string
                    example:  "Hello Swagger!"

ステップ3：Dockerコンテナの起動

ターミナルで’docker-compose.yml’ファイルが保存されたディレクトリに移動し、以下のコマンドを実行します。

docker-compose up -d

これでSwagger EditorとSwagger UIが起動します。

ステップ4：アクセス方法

Swagger Editor：http://localhost:8001
Swagger UI：http://localhost:8002

上記のようなリンクへ飛ぶと以下のようなページが開きます。

swagger editor
Swagger UI

4.Swagger UIでリクエストとレスポンス確認

ステップ1：Swagger UIにアクセス

ブラウザで’http://localhost:8002’にアクセスすると、先ほど作成したOpenAPI仕様書に基づいたインタラクティブなUIが表示されます。

ステップ2：リクエスト送信とレスポンス確認

「/helloSwagger」エンドポイントを選択し、「Try it out」> 「Execute」をクリックしてリクエストを送信すると、以下のようにレスポンスが返ってきます。

API Test

5. Swagger Codegenでコード自動生成

次に、Swagger Codegenを使ってAPI仕様書からクライアントコードやサーバースタブを自動生成する方法を紹介します。

コード生成手順

前提条件：Java 7以上がインストールされていること

①Swagger Codegen CLIをインストールします

Homebrewを使う場合：

brew install swagger-codegen

wgetを使う場合：

wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.19/swagger-codegen-cli-3.0.19.jar

②以下のコマンドでコード生成を実行します

Homebrewを使ってSwagger Codegenをインストールした場合：

swagger-codegen generate -i <Swagger仕様書のパス> -l <生成したい言語> -o <出力先>

wget を使ってSwagger Codegenをインストールした場合：

java -jar swagger-codegen-cli.jar generate -i <Swagger仕様書のパス> -l <生成したい言語> -o<出力先>

生成されたコードの一部(Java):

public class DefaultApi {
  private ApiClient apiClient;
  private Map<String, String> headers;

  public DefaultApi() {
    this(Configuration.getDefaultApiClient());
  }

  public DefaultApi(ApiClient apiClient) {
    this.apiClient = apiClient;
  }

  public ApiClient getApiClient() {
    return apiClient;
  }

  public void setApiClient(ApiClient apiClient) {
    this.apiClient = apiClient;
  }

  public void setHeadersOverrides(Map<String, String> headers) {
    this.headers = headers;
  }
}

生成されたコードの中から必要なファイルをご自身のプロジェクトに追加して利用することができます。

6.Swagger活用場面

私自身は新人エンジニアとして以下の場面でSwaggerを活用しています。

  • 学習ツールとして：HTTPリクエスト/レスポンスの仕組みを理解するのに役立ちます。

  • モックサーバとして：バックエンドが完成していなくても、Swaggerでモックを作成することでそれ以外の部分の開発を進めることができます。

まとめ

今回は、DockerによるSwagger環境構築からSwaggerUIでのリクエスト確認、さらにSwagger Codegenによるコード自動生成までを紹介しました。

これらのツールを組み合わせることで、効率的なAPI開発が可能になります。ぜひ試してみてください！

ソフトバンクアドベントカレンダー2024は、ついに明日で最終日の25日を迎えます！最終日もお楽しみに！

 ＼ 業務課題をデジタルで支援 ／

デジタルツールの選定から導入の手引きまで、中小規模のお客さまへわかりやすくお伝えします。

中小規模のお客さま向けサイトをみる

メールマガジン登録（無料）
ビジネスに役立つ記事やウェビナー情報をお届けします。

おすすめの記事

条件に該当するページがございません

法人のお客さま向け イベント

イベント・セミナー

ビジネスに役立つ 資料ダウンロード

資料ダウンロード

「今」と「未来」を発信 ソフトバンクのビジネスブログ

ビジネスブログ

クラウドテクノロジーブログ

クラウドテクノロジーブログ