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
就可以触发。
还内置了各种语言的请求接口脚本插件:
而且样式也不错,是不是很赞,喜欢的点个赞吧。