FastAPI OpenAPI文档：自定义HTML的完整指南

FastAPI OpenAPI文档自定义HTML的完整指南【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapiFastAPI作为一款高性能、易学习的现代Python Web框架其自动生成的OpenAPI文档Swagger UI和ReDoc是提升API开发效率的重要工具。本文将详细介绍如何自定义FastAPI的OpenAPI文档HTML包括使用自定义CDN和自托管静态资源两种方案帮助开发者打造符合项目需求的文档界面。为什么需要自定义OpenAPI文档默认情况下FastAPI的文档资源JavaScript和CSS文件通过CDN加载这在大多数场景下工作良好。但在以下情况你可能需要自定义文档HTML所在地区限制特定CDN访问项目需要在无网络环境下运行企业内部网络安全策略限制外部资源加载需要定制文档界面风格以匹配品牌形象方案一使用自定义CDN加速文档资源禁用默认文档路由首先需要禁用FastAPI自动生成的文档路由通过在创建FastAPI实例时将docs_url和redoc_url设置为None实现from fastapi import FastAPI app FastAPI(docs_urlNone, redoc_urlNone)实现自定义文档路由利用FastAPI提供的get_swagger_ui_html和get_redoc_html函数创建自定义文档路由并指定新的CDN地址。以下示例使用unpkg.com作为替代CDNfrom fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html, get_swagger_ui_oauth2_redirect_html app.get(/docs, include_in_schemaFalse) async def custom_swagger_ui_html(): return get_swagger_ui_html( openapi_urlapp.openapi_url, titleapp.title - Swagger UI, oauth2_redirect_urlapp.swagger_ui_oauth2_redirect_url, swagger_js_urlhttps://unpkg.com/swagger-ui-dist5/swagger-ui-bundle.js, swagger_css_urlhttps://unpkg.com/swagger-ui-dist5/swagger-ui.css, ) app.get(app.swagger_ui_oauth2_redirect_url, include_in_schemaFalse) async def swagger_ui_redirect(): return get_swagger_ui_oauth2_redirect_html() app.get(/redoc, include_in_schemaFalse) async def redoc_html(): return get_redoc_html( openapi_urlapp.openapi_url, titleapp.title - ReDoc, redoc_js_urlhttps://unpkg.com/redoc2/bundles/redoc.standalone.js, )图1使用自定义CDN加载的Swagger UI文档界面方案二自托管文档静态资源如果需要完全控制文档资源可将相关静态文件下载到本地并由FastAPI应用本身提供服务。项目结构准备创建如下项目结构专门存放文档所需的静态资源. ├── app │ ├── __init__.py │ ├── main.py └── static/ ├── redoc.standalone.js ├── swagger-ui-bundle.js └── swagger-ui.css下载必要的静态文件从官方CDN下载以下文件并保存到static目录Swagger UI:swagger-ui-bundle.jsswagger-ui.cssReDoc:redoc.standalone.js配置静态文件服务使用FastAPI的StaticFiles挂载静态文件目录from fastapi.staticfiles import StaticFiles app.mount(/static, StaticFiles(directorystatic), namestatic)配置文档使用本地资源修改文档路由将资源URL指向本地静态文件app.get(/docs, include_in_schemaFalse) async def custom_swagger_ui_html(): return get_swagger_ui_html( openapi_urlapp.openapi_url, titleapp.title - Swagger UI, oauth2_redirect_urlapp.swagger_ui_oauth2_redirect_url, swagger_js_url/static/swagger-ui-bundle.js, swagger_css_url/static/swagger-ui.css, ) app.get(/redoc, include_in_schemaFalse) async def redoc_html(): return get_redoc_html( openapi_urlapp.openapi_url, titleapp.title - ReDoc, redoc_js_url/static/redoc.standalone.js, )图2使用本地静态资源加载的ReDoc文档界面测试自定义文档完成配置后启动应用并访问以下地址测试效果Swagger UI: http://127.0.0.1:8000/docsReDoc: http://127.0.0.1:8000/redoc对于自托管方案可断开网络连接测试离线访问能力确保文档仍能正常加载。总结通过本文介绍的两种方案你可以灵活控制FastAPI文档的资源加载方式。自定义CDN方案适合需要替换资源来源的场景而自托管方案则适用于离线环境或严格的网络安全要求。两种方案均基于FastAPI提供的原生功能实现简单且不影响核心功能。完整的代码示例可参考项目中的docs_src/custom_docs_ui/tutorial001_py310.py和docs_src/custom_docs_ui/tutorial002_py310.py文件。根据实际需求选择合适的方案让FastAPI文档更好地服务于你的项目开发。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考