fastapi集成stoplight-elements openapi接口文档1. 前言 fastapi内置了 swag

1. 前言

fastapi内置了 swagger 和 redoc 两种openapi接口文档，但是前者有点丑，后者不支持 try it out只能看不能调试。所以琢磨着有没有第三者可以替代，最终找到了 stoplight ，但是fastapi并不支持，于是乎经过一番查找，在fastapi的pull中找到了贡献者提供的集成方法Add Stoplight Elements as built-in docs tool，但是一直没有被作者合并，但是今天我们将其抽出来，可以集成在自己的项目中使用，还是很不错的。

2. 直接上干货

本身这个也没什么过多讲的，这里只是作为一个记录，如何将 stoplight 配置进你的项目当中可以使用。

2.1 创建一个文件

该文件我暂且命名为 elements.py，与 main.py 在同级目录下，内容为:

from enum import Enum

from fastapi.responses import HTMLResponse


class TryItCredentialPolicyOptions(Enum):
    OMIT = "omit"
    include = "include"
    SAME_ORIGIN = "same-origin"


class LayoutOptions(Enum):
    SIDEBAR = "sidebar"
    STACKED = "stacked"


class RouterOptions(Enum):
    HISTORY = "history"
    HASH = "hash"
    MEMORY = "memory"
    STATIC = "static"


def get_stoplight_elements_html(
    *,
    openapi_url: str,
    title: str,
    stoplight_elements_js_url: str = "https://unpkg.com/@stoplight/elements/web-components.min.js",
    stoplight_elements_css_url: str = "https://unpkg.com/@stoplight/elements/styles.min.css",
    stoplight_elements_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
    api_description_document: str = "",
    base_path: str = "",
    hide_internal: bool = False,
    hide_try_it: bool = False,
    try_it_cors_proxy: str = "",
    try_it_credential_policy: TryItCredentialPolicyOptions = TryItCredentialPolicyOptions.OMIT,
    layout: LayoutOptions = LayoutOptions.SIDEBAR,
    logo: str = "",
    router: RouterOptions = RouterOptions.HISTORY,
) -> HTMLResponse:
    """Referenced from https://github.com/fastapi/fastapi/pull/5168"""

    html = f"""
    <!doctype html>
    <html lang="en">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
        <title>{title}</title>
        <link rel="shortcut icon" href="{stoplight_elements_favicon_url}">
        <script src="{stoplight_elements_js_url}"></script>
        <link rel="stylesheet" href="{stoplight_elements_css_url}">
    </head>
    <body>
        <elements-api
            {f'apiDescriptionUrl="{openapi_url}"' if openapi_url != '' else ''}
            {f'apiDescriptionDocument="{api_description_document}"' if api_description_document != '' else ''}
            {f'basePath="{base_path}"' if base_path != '' else ''}
            {'hideInternal="true"' if hide_internal is True else ''}
            {'hideTryIt="true"' if hide_try_it is True else ''}
            {f'tryItCorsProxy="{try_it_cors_proxy}"' if try_it_cors_proxy != '' else ''}
            tryItCredentialPolicy="{try_it_credential_policy.value}"
            layout="{layout.value}"
            {f'logo="{logo}"' if logo != '' else ''}
            router="{router.value}"
        />
    </body>
    </html>
    """
    return HTMLResponse(html)

2.2 在main.py中导入使用

from fastapi import FastAPI, Request
from .elements import get_stoplight_elements_html


app = FastAPI(
    title="stoplight demo",
    description="stoplight demo",
    lifespan=lifespan,
)

# stoplight_elements doc
@app.get("/elements", include_in_schema=False)
async def api_documentation(request: Request):
    """Add stoplight elements api doc. https://dev.to/amal/replacing-fastapis-default-api-docs-with-elements-391d"""

    return get_stoplight_elements_html(
        openapi_url=app.openapi_url, title=app.title + " - elements", base_path="elements"
    )

经此配置完毕后，我们启动fastapi项目，访问 http://localhost:8000/elements 就可以看到接口文档了。

样子嘛，大概如下图所示：在这里插入图片描述

它可以支持调试接口，右侧的 send api request 就可以触发。

还内置了各种语言的请求接口脚本插件：

并且样式也不错，是不是很赞，喜欢的点个赞吧。