Flask-RESTX Swagger ドキュメント表示を無効にするいくつかの方法

FlaskでRest APIを実装するための拡張 Flask RESTX には、Rest API仕様を表示してくれる機能が内蔵されています。その実態はSwaggerというAPI仕様を記述するJSONドキュメントと、それを見やすく表示してくれるSwagger UIの組み合わせ。ほかの多くのWebフレームワークにも同じ機能が載っています。

from flask import Flask
from flask_restx import Api, Resource, fields


app = Flask(__name__)
api = Api(app)

@api.route("/sample")
class SampleResource(Resource):
    def get(self):
        """ サンプル """
        pass

    @api.expect(api.model("Sample", model={"name": fields.String}))
    def post(self):
        """ サンプルを追加 """
        pass

開発時には便利ですが、公開環境ではAPI仕様を見れるようにはしたくないケースも多くあります。そのためにとれる方法を紹介します。

引数 doc にFalse 指定

Apiクラスの引数 doc に False を指定することで、Swagger UI を無効にできます。

api = Api(app, doc=False)

ただし、表示されなくなるのはSwagger UIだけで、JSONで配信されるSwaggerドキュメントは /swagger.json は依然として公開されたままです。

nginxでHTTP/404 へrewrite

nginxでプロキシしてるならその設定のなかで、swaggerドキュメントへのリクエストをHTTP/404にリライトすることで、JSONファイルへのアクセスを防げます。

location ^~ /swagger.json {
  rewrite ^(.*)$ /404 redirect;
}

次に述べるやりかたを知るまでは、この方法しかないと思っていました。

init_app で引数 add_specs を指定

Flask拡張は、インスタンス作成時にFlaskオブジェクト (app) を渡して有効にする方法と、インスタンスを作ったあとにinit_appにFlaskオブジェクトを渡す方法どちらかを選べるようになっています。

app = Flask(__name__)

api = Api(app)
# あるいは
api = Api()
api.init_app(app)

init_appの引数に add_specs=False を指定すると、swagger JSONファイルの配信も止めることができるみたいです。

api = Api()
api.init_app(app, add_specs=True)

みたいです、というのはdocコメントにその記述がないんですよねえ……。

In [10]: api.init_app?
Signature: api.init_app(app, **kwargs)
Docstring:
Allow to lazy register the API on a Flask application::

>>> app = Flask(__name__)
>>> api = Api()
>>> api.init_app(app)

:param flask.Flask app: the Flask application object
:param str title: The API title (used in Swagger documentation)
:param str description: The API description (used in Swagger documentation)
:param str terms_url: The API terms page URL (used in Swagger documentation)
:param str contact: A contact email for the API (used in Swagger documentation)
:param str license: The license associated to the API (used in Swagger documentation)
:param str license_url: The license page URL (used in Swagger documentation)
File:      ~/.local/share/virtualenvs/restx-7s1H6SJg/lib/python3.9/site-packages/flask_restx/api.py
Type:      method

使っていいオプションなのかどうか、よくわかりません。

参考