完全ガイド：FlaskアプリのAPIドキュメンテーション生成

FlaskフレームワークでWebアプリを作った後、そのAPIドキュメンテーションを生成するには、どうしたらいいですか？本文では、Flaskフレームワークで利用可能な拡張機能であるFlasggerを使って、簡単にFlaskアプリのAPIドキュメンテーションを生成する方法を皆さんに紹介します。

FlaskアプリのAPIドキュメンテーションはなぜ必要？

FlaskアプリのAPIドキュメンテーションは非常に不可欠なものになります。APIドキュメンテーションを行うと、様々なメリットが得られるようになると考えられています。

• APIを利用する開発者にとって、ドキュメントはAPIの仕様を理解する上で不可欠。ドキュメントがないとAPIの利用は困難。
• APIの入力、出力、エラー、認証方法などの技術的詳細がドキュメント上に明記されている必要がある。
• APIの変更履歴をドキュメント上で管理できるようにしておくことが望ましい。
• インタラクティブなドキュメント(Swagger UIなど)を作成することで、開発者が実際にAPIを試すことができる。
• ドキュメントを自動生成することで、コードの変更に追従しやすく保守コストが下がる。

つまり、APIドキュメントは、APIの開発者と利用者の橋渡し的な存在であり、APIの動作をスムーズに理解しやすくすることが主目的です。APIの正しい利用と開発の効率化に不可欠な存在といえます。

それでは、FlaskアプリケーションのAPIドキュメンテーションを生成するためには、どうしたらいいですか？次は、Flasggerというツールを皆さんに紹介しようと思います。

Flasggerとは

FlaskアプリのAPIドキュメンテーションを生成するために、Flasggerを利用することが便利な対策です。Flasggerは、FlaskアプリケーションのAPIドキュメンテーションを簡単に作成できるツールです。

主な特徴は以下の通りです。

• Swagger UIを利用してインタラクティブなAPIドキュメントを生成できる
• OpenAPIスペックに準拠したドキュメントを出力できる
• YAMLやPythonデコレータを使用してドキュメントを定義できる
• Flask view関数とパラメータを自動的に取得しドキュメントに反映させることができる
• バリデータやマーシャラを利用した入力/出力の定義ができる

Flasggerを使うことで、Swagger UIベースの視覚的なAPIドキュメントを簡単にFlaskアプリに追加することができます。 APIの開発とドキュメント作成を同時に進められるので、開発速度の向上やプロジェクトの規模拡大に寄与します。FlaskでWEB APIサーバを作成する際には強力なツールだと言えます。

Flasggerを使ってAPIドキュメンテーションを生成する方法

それでは、Flasggerを使ってFlaskアプリのAPIドキュメンテーションを生成するには、どうしたらいいですか？次は、Flasggerの詳細な利用ガイドを皆さんに紹介しますので、ご参照ください。

Flasggerのインストール

Flasggerをインストールする前提として、setuptoolsがパソコンにインストールされる必要があります。それでは、次のコマンドを利用して、setuptoolsをインストールした上、Flasggerというツールもインストールしましょう。

pip install -U setuptools
pip install flasgger

routeの注釈を記述

from flask import Flask, jsonifyfrom flasgger import Swaggerapp = Flask(__name__)
swagger = Swagger(app)

@app.route('/colors/<palette>/')def colors(palette):
    """Example endpoint returning a list of colors by palette    This is using docstrings for specifications.    ---    parameters:      - name: palette        in: path        type: string        enum: ['all', 'rgb', 'cmyk']        required: true        default: all    definitions:      Palette:        type: object        properties:          palette_name:            type: array            items:              $ref: '#/definitions/Color'      Color:        type: string    responses:      200:        description: A list of colors (may be filtered by palette)        schema:          $ref: '#/definitions/Palette'        examples:          rgb: ['red', 'green', 'blue']    """all_colors = {
        'cmyk': ['cyan', 'magenta', 'yellow', 'black'],
        'rgb': ['red', 'green', 'blue']
    }
    if palette == 'all':
        result = all_colorselse:
        result = {palette: all_colors.get(palette)}

    return jsonify(result)

app.run(debug=True)

上記のコードはFlaskとFlasggerを使ってシンプルなAPIエンドポイントを作成し、Swagger UIベースのインタラクティブなドキュメントを自動生成するサンプルです。

まずFlaskアプリを作成し、FlasggerでSwaggerスペックのためのオブジェクトを初期化しています。

次に@app.routeデコレータで/colors/<palette>/というエンドポイントを定義していて、paletteパラメータで色のパレットを指定できます。

関数直下のドキュメント文字列は、このエンドポイントのSwaggerスペックを記述しています。YAMLフォーマットでパラメータ、レスポンススキーマ、例などを定義しています。

関数Bodyはパレットに応じて色のリストをJSONで返しています。

これを実行すると http://localhost:5000/apidocs/#/ でインタラクティブなドキュメントにアクセスでき、このAPIを試すことができます。

Flasggerはview関数のドキュメント文字列から自動的にスペックを生成するので、コード変更をドキュメントに簡単に反映できるのが大きなメリットです。

ブラウザでUrlを開く

ここで、次のURLを開くことで、Swagger UIのドキュメントが生成されました。

http://localhost:5000/apidocs

Apidog：より便利なドキュメンテーション生成ツール

Flasggerの代わりに、Apidogはより便利のAPIドキュメンテーション生成ツールです。Apidogは、非常に優れているAPI設計、テスト用ツールとして、FlaskのAPIを簡単にテストすることができますし、そして、リクエストの情報に基づいて簡単にAPIドキュメンテーションを生成することもできます。

次のように、非常に直感的なUIでFlaskで作成されたAPIを簡単にテストすることができます。そして、当該リクエストの情報を保存して、それに基づいて1クリックでAPIドキュメンテーションを生成することもできます。

ApidogのAPIドキュメンテーション：

まとめ

FlaskアプリのAPIにはドキュメントが重要で、開発効率化や利用者への支援に必須です。Flasggerを使うとSwagger UIベースのインタラクティブドキュメントを簡単作成できます。

また、その代替ツールのApidogは、Flask APIを簡単にテストすることができますし、送信済みのリクエストに基づいて簡単にAPIドキュメンテーションを作成することができます。

そこで、FlaskでのWEB API開発時、FlasggerやApidogを活用することで、開発速度と保守性を高められるでしょう。ドキュメント生成ツールの選択と併用がポイントになると考えます。