先生と生徒の会話形式で理解しよう

生徒

「FlaskでAPIを作ったんですが、これって使い方の説明とかを自動で見せる方法ってありますか？」

先生

「はい、Swagger UIというツールを使えば、APIの使い方をわかりやすくWeb画面で表示することができますよ。」

生徒

「Swagger UIって何ですか？難しそう…」

先生

「大丈夫です。プログラミング初心者でも簡単に使えるように、今回は丁寧に説明していきます！」

1. Swagger UIとは？APIドキュメントを自動で見せる便利ツール

まず、「Swagger（スワッガー）」とは、API（エーピーアイ）の使い方を見える化してくれるツールです。

APIとは、簡単に言うと「コンピューター同士のおしゃべりのルール」です。人間が見てもわかるように、Swagger UIはWeb画面でボタンを押すだけで、APIを試せる便利な仕組みです。

たとえば「名前を登録するAPI」や「データを読み取るAPI」があると、それぞれの説明、使い方、入力の仕方を画面で確認できるようになります。

2. FlaskとSwagger UIを組み合わせる方法

PythonでAPIを作るときによく使うのがFlask（フラスク）という軽量なWebフレームワークです。このFlaskにSwagger UIを組み込むには、flasgger（フラスガー）という拡張ライブラリを使います。

flasggerを使うことで、Pythonコードの中にAPIの説明を書くだけで、Swagger UIが自動でその内容を読み取って画面を作ってくれます。

3. flasggerのインストール方法

まずは、flasggerをインストールしましょう。以下のコマンドをターミナル（黒い画面）で入力してください。


pip install flasgger

pipとは、Pythonのライブラリをインストールするためのコマンドです。

4. 実際にFlaskとSwagger UIを使ってみよう

では、簡単なAPIとSwagger UIの画面を作ってみましょう。


from flask import Flask, request, jsonify
from flasgger import Swagger

app = Flask(__name__)
swagger = Swagger(app)

@app.route("/hello", methods=["GET"])
def hello():
    """
    シンプルなあいさつAPI
    ---
    responses:
      200:
        description: あいさつのメッセージを返します
    """
    return jsonify(message="こんにちは、FlaskとSwaggerの世界へようこそ！")

if __name__ == "__main__":
    app.run(debug=True)

このコードを実行したら、ブラウザで http://localhost:5000/apidocs を開いてください。すると、Swagger UIの画面が表示され、/hello というAPIが一覧に出てきます。

5. ドキュメント部分の書き方を理解しよう

API関数の中にある三重クォート（"""）の中が、Swagger UIに表示される内容です。これは「YAML（ヤムル）」という書き方で、見た目にわかりやすく書けます。

descriptionは説明文、responsesは「どんな応答が返ってくるか」を意味します。

6. 入力パラメータを付け加えてみよう

APIに入力が必要な場合もSwagger UIで見やすく表示できます。以下は、名前を受け取ってあいさつするAPIの例です。


@app.route("/greet", methods=["GET"])
def greet():
    """
    名前を使ってあいさつするAPI
    ---
    parameters:
      - name: name
        in: query
        type: string
        required: true
        description: あいさつする相手の名前
    responses:
      200:
        description: 名前付きのあいさつメッセージを返します
    """
    name = request.args.get("name")
    return jsonify(message=f"こんにちは、{name}さん！")

Swagger UIでは、「name」という入力欄が表示され、そこに文字を入力して「Try it out」ボタンを押すと結果が見られます。

7. Swagger UIを表示するURLと注意点

flasggerを使うと、/apidocs というURLにSwagger UIが表示されます。もし表示されないときは、プログラムが実行中であること、flasggerが正しくインストールされていることを確認してください。

8. なぜSwagger UIを使うと便利なのか

プログラムに詳しくない人でも、Swagger UIならボタン操作だけでAPIの動きを確認できます。たとえば、開発チームの中で「APIの使い方がわからない」という人がいても、Swagger UIの画面を見せるだけで済みます。

また、Swagger UIがあると、他の人があなたのAPIを試すときに迷わなくなるので、エラーやトラブルも減ります。

9. よくあるエラーとその対処法

プログラム初心者の方は、以下のようなエラーに注意しましょう。

モジュールが見つからない： pipでflasggerのインストールを忘れていないか確認しましょう。
サーバーが起動しない： if __name__ == "__main__": 以下のコードを正しく書いているか確認しましょう。
Swagger UIが表示されない： http://localhost:5000/apidocs にアクセスしているか確認しましょう。

まとめ

FlaskでAPIを作成したあと、その使い方をほかの人にわかりやすく伝えるためには、ただコードを書くだけでは不十分になることがあります。とくにAPIは画面がない仕組みなので、どのURLにアクセスすればいいのか、どんな入力が必要なのか、どんな応答が返ってくるのかが一目では見えません。そこで役立つのがSwagger UIで、今回の記事ではその基本的な使い方と組み込む手順を丁寧にたどってきました。Swagger UIがあると、実際のAPIをブラウザで確認しながら試せるため、開発者どうしの理解がスムーズになり、第三者に説明するときの負担も少なくなります。また、Flaskと一緒に使うflasggerというライブラリは、Pythonのコードの中に説明を書くことで自動でAPIドキュメントを作り出すため、複雑な準備作業なしで導入できるのが魅力です。プログラミング初心者でも扱いやすいという点は大きな安心材料ですし、実際の開発現場でもSwagger UIは幅広く使われているため、学んでおく価値はとても高いです。入力パラメータの指定方法や、YAML形式での説明の書き方を理解すると、APIにどんな項目が必要なのか、どんな仕様にすべきかが自然と整理されていきます。さらに、APIドキュメントが整っていることで、開発チーム内での情報共有が楽になり、仕様書と実装の食い違いも減ります。とくに複数のAPIがあるプロジェクトでは、一覧でAPIが確認できる利点は非常に大きいです。更新が必要になったときにもコードの中の説明を変えるだけでドキュメントも自動で変わるため、手間をかけずに正しい情報を維持できます。このように、Swagger UIは単なる補助ツールではなく、API開発全体を支える重要な役割を果たしています。記事の中で触れたように、実行後は/apidocsというURLにアクセスするだけでドキュメントが表示され、実際にボタンを押してAPIを試すことができます。名前を入力してあいさつを返すAPIの例では、Swagger UIの入力欄で値を指定して動作を確認する流れがひと目で理解できたはずです。こうした操作が画面で完結するため、コードを書いた本人だけでなく、プログラムに慣れていない人でも安心して利用できます。また、今回のような基本的な使い方が身につくと、さらに高度な設定にも挑戦できるようになります。複数のパラメータを扱うAPIや、JSON形式のリクエストを受け取るAPI、POSTでデータを送るAPIなど、さまざまな仕様をSwagger UIで表現できるようになります。ひとつひとつを丁寧に試しながら仕様と動作を合わせていくことで、APIの品質そのものが自然と高まっていきます。 Flaskを使ったAPI開発は、初心者にとって学びやすい環境でありながら、実務的な構築にも十分対応できます。そこにSwagger UIを組み合わせることで、APIの使い方を説明する手間が減り、開発者・利用者双方にとって見通しの良いプロジェクトを実現できます。今回の内容を自分の手で動かしながら学んでいけば、将来より大きなWebサービスや本格的なAPIシステムを作る際にも確かな基礎として役立つはずです。

サンプルコード（確認用）

学んだ内容の整理として、もう一つシンプルなAPIドキュメントの例を載せておきます。


@app.route("/sample", methods=["GET"])
def sample():
    """
    サンプルAPI
    ---
    responses:
      200:
        description: サンプルデータを返します
    """
    return jsonify(data="サンプルです")

このように、関数内の説明を書くだけでSwagger UIが内容を読み取り、画面に自動で反映します。とてもシンプルですが、こうした積み重ねが実践的なAPI設計につながるため、まずは身近な例から試していくのが良い練習になります。

先生と生徒の振り返り会話

生徒

「今日の内容でSwagger UIの便利さがすごくよくわかりました。画面で操作できるのは思ったよりわかりやすかったです。」

先生

「そうですね。特にAPIは目に見える部分が少ないので、説明画面があると理解しやすくなりますし、動作確認も簡単になります。」

生徒

「YAMLで説明を書くところは慣れるまで少し不安でしたが、書く内容自体はシンプルで安心しました。」

先生

「YAMLは慣れると読みやすくて書きやすいので、少しずつ感覚をつかむと良いですよ。APIの仕様を整理するのにも役立ちます。」

生徒

「次はもっと複雑なAPIもSwagger UIで試してみたいです！」