カスタムドキュメント UI 静的アセット (セルフホスティング)¶

API ドキュメントは **Swagger UI** と **ReDoc** を使用しており、それぞれに JavaScript と CSS ファイルが必要です。

デフォルトでは、これらのファイルは CDN から提供されます。

ただし、カスタマイズすることも可能です。特定の CDN を設定したり、ファイルを自分で提供したりできます。

JavaScript と CSS のカスタム CDN¶

たとえば、https://unpkg.com/ など、別の CDN を使用したいとします。

これは、たとえば、一部の URL が制限されている国に住んでいる場合に役立ちます。

自動ドキュメントを無効にする¶

最初のステップは、自動ドキュメントを無効にすることです。デフォルトでは、これらはデフォルトの CDN を使用するためです。

無効にするには、FastAPI アプリを作成するときに URL を None に設定します

from fastapi import FastAPI
from fastapi.openapi.docs import (
    get_redoc_html,
    get_swagger_ui_html,
    get_swagger_ui_oauth2_redirect_html,
)

app = FastAPI(docs_url=None, redoc_url=None)


@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Swagger UI",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js",
        swagger_css_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css",
    )


@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
    return get_swagger_ui_oauth2_redirect_html()


@app.get("/redoc", include_in_schema=False)
async def redoc_html():
    return get_redoc_html(
        openapi_url=app.openapi_url,
        title=app.title + " - ReDoc",
        redoc_js_url="https://unpkg.com/redoc@next/bundles/redoc.standalone.js",
    )


@app.get("/users/{username}")
async def read_user(username: str):
    return {"message": f"Hello {username}"}

カスタムドキュメントを含める¶

これで、カスタムドキュメントの*パス操作*を作成できます。

FastAPI の内部関数を再利用してドキュメントの HTML ページを作成し、必要な引数を渡すことができます

openapi_url: ドキュメントの HTML ページが API の OpenAPI スキーマを取得できる URL。ここでは、属性 app.openapi_url を使用できます。
title: API のタイトル。
oauth2_redirect_url: デフォルトを使用するには、ここで app.swagger_ui_oauth2_redirect_url を使用できます。
swagger_js_url: Swagger UI ドキュメントの HTML が **JavaScript** ファイルを取得できる URL。これはカスタム CDN URL です。
swagger_css_url: Swagger UI ドキュメントの HTML が **CSS** ファイルを取得できる URL。これはカスタム CDN URL です。

ReDoc についても同様です...

from fastapi import FastAPI
from fastapi.openapi.docs import (
    get_redoc_html,
    get_swagger_ui_html,
    get_swagger_ui_oauth2_redirect_html,
)

app = FastAPI(docs_url=None, redoc_url=None)


@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Swagger UI",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js",
        swagger_css_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css",
    )


@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
    return get_swagger_ui_oauth2_redirect_html()


@app.get("/redoc", include_in_schema=False)
async def redoc_html():
    return get_redoc_html(
        openapi_url=app.openapi_url,
        title=app.title + " - ReDoc",
        redoc_js_url="https://unpkg.com/redoc@next/bundles/redoc.standalone.js",
    )


@app.get("/users/{username}")
async def read_user(username: str):
    return {"message": f"Hello {username}"}

ヒント

swagger_ui_redirect の*パス操作*は、OAuth2 を使用する場合のヘルパーです。

API を OAuth2 プロバイダーと統合すると、認証して取得した資格情報で API ドキュメントに戻ることができます。そして、実際の OAuth2 認証を使用して対話できます。

Swagger UI はバックグラウンドで処理しますが、この「リダイレクト」ヘルパーが必要です。

テストするためのパス操作を作成する¶

すべてが機能することをテストするために、*パス操作*を作成します

from fastapi import FastAPI
from fastapi.openapi.docs import (
    get_redoc_html,
    get_swagger_ui_html,
    get_swagger_ui_oauth2_redirect_html,
)

app = FastAPI(docs_url=None, redoc_url=None)


@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Swagger UI",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js",
        swagger_css_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css",
    )


@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
    return get_swagger_ui_oauth2_redirect_html()


@app.get("/redoc", include_in_schema=False)
async def redoc_html():
    return get_redoc_html(
        openapi_url=app.openapi_url,
        title=app.title + " - ReDoc",
        redoc_js_url="https://unpkg.com/redoc@next/bundles/redoc.standalone.js",
    )


@app.get("/users/{username}")
async def read_user(username: str):
    return {"message": f"Hello {username}"}

テストする¶

これで、http://127.0.0.1:8000/docs にあるドキュメントにアクセスしてページをリロードできるはずです。新しい CDN からアセットがロードされます。

ドキュメント用の JavaScript と CSS のセルフホスティング¶

JavaScript と CSS のセルフホスティングは、たとえば、インターネットにアクセスできないオフライン状態やローカルネットワークでもアプリを動作させ続ける必要がある場合に役立ちます。

ここでは、これらのファイルを同じ FastAPI アプリで自分で提供し、ドキュメントがそれらを使用するように設定する方法を説明します。

プロジェクトファイル構造¶

プロジェクトのファイル構成が以下のようになっているとします。

.
├── app
│   ├── __init__.py
│   ├── main.py

これらの静的ファイルを格納するディレクトリを作成します。

新しいファイル構成は以下のようになります。

.
├── app
│   ├── __init__.py
│   ├── main.py
└── static/

ファイルをダウンロードする¶

ドキュメントに必要な静的ファイルをダウンロードし、static/ ディレクトリに配置します。

各リンクを右クリックし、名前を付けてリンク先を保存... のようなオプションを選択すれば、ダウンロードできるでしょう。

Swagger UI は以下のファイルを使用します。

そして、ReDoc は以下のファイルを使用します。

redoc.standalone.js

その後、ファイル構成は以下のようになります。

.
├── app
│   ├── __init__.py
│   ├── main.py
└── static
    ├── redoc.standalone.js
    ├── swagger-ui-bundle.js
    └── swagger-ui.css

静的ファイルを提供する¶

StaticFiles をインポートします。
StaticFiles() インスタンスを特定のパスに「マウント」します。

from fastapi import FastAPI
from fastapi.openapi.docs import (
    get_redoc_html,
    get_swagger_ui_html,
    get_swagger_ui_oauth2_redirect_html,
)
from fastapi.staticfiles import StaticFiles

app = FastAPI(docs_url=None, redoc_url=None)

app.mount("/static", StaticFiles(directory="static"), name="static")


@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Swagger UI",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="/static/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui.css",
    )


@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
    return get_swagger_ui_oauth2_redirect_html()


@app.get("/redoc", include_in_schema=False)
async def redoc_html():
    return get_redoc_html(
        openapi_url=app.openapi_url,
        title=app.title + " - ReDoc",
        redoc_js_url="/static/redoc.standalone.js",
    )


@app.get("/users/{username}")
async def read_user(username: str):
    return {"message": f"Hello {username}"}

静的ファイルをテストする¶

アプリケーションを起動し、http://127.0.0.1:8000/static/redoc.standalone.js にアクセスします。

ReDoc 用の非常に長い JavaScript ファイルが表示されるはずです。

ファイルの先頭は以下のようになっているでしょう。

/*!
 * ReDoc - OpenAPI/Swagger-generated API Reference Documentation
 * -------------------------------------------------------------
 *   Version: "2.0.0-rc.18"
 *   Repo: https://github.com/Redocly/redoc
 */
!function(e,t){"object"==typeof exports&&"object"==typeof m

...

これは、アプリケーションから静的ファイルを提供できていること、そしてドキュメント用の静的ファイルを正しい場所に配置したことを確認します。

これで、ドキュメント用にこれらの静的ファイルを使用するようにアプリケーションを設定できます。

静的ファイルの自動ドキュメントを無効にする¶

カスタムCDNを使用する場合と同様に、最初のステップは自動ドキュメントを無効にすることです。自動ドキュメントはデフォルトでCDNを使用するためです。

無効にするには、FastAPI アプリを作成するときに URL を None に設定します

from fastapi import FastAPI
from fastapi.openapi.docs import (
    get_redoc_html,
    get_swagger_ui_html,
    get_swagger_ui_oauth2_redirect_html,
)
from fastapi.staticfiles import StaticFiles

app = FastAPI(docs_url=None, redoc_url=None)

app.mount("/static", StaticFiles(directory="static"), name="static")


@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Swagger UI",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="/static/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui.css",
    )


@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
    return get_swagger_ui_oauth2_redirect_html()


@app.get("/redoc", include_in_schema=False)
async def redoc_html():
    return get_redoc_html(
        openapi_url=app.openapi_url,
        title=app.title + " - ReDoc",
        redoc_js_url="/static/redoc.standalone.js",
    )


@app.get("/users/{username}")
async def read_user(username: str):
    return {"message": f"Hello {username}"}

静的ファイルのカスタムドキュメントを含める¶

カスタムCDNの場合と同様に、カスタムドキュメントの *パス操作* を作成できます。

繰り返しますが、FastAPIの内部関数を使用してドキュメント用のHTMLページを作成し、必要な引数を渡すことができます。

openapi_url: ドキュメントの HTML ページが API の OpenAPI スキーマを取得できる URL。ここでは、属性 app.openapi_url を使用できます。
title: API のタイトル。
oauth2_redirect_url: デフォルトを使用するには、ここで app.swagger_ui_oauth2_redirect_url を使用できます。
swagger_js_url: Swagger UIドキュメントのHTMLが **JavaScript** ファイルを取得できるURL。 **これは、独自のアプリケーションが提供しているURLです**。
swagger_css_url: Swagger UIドキュメントのHTMLが **CSS** ファイルを取得できるURL。 **これは、独自のアプリケーションが提供しているURLです**。