Recursos Estáticos Personalizados para la Docs UI (self hosting)¶
🌐 Traducción por IA y humanos
Esta traducción fue hecha por IA guiada por humanos. 🤝
Podría tener errores al interpretar el significado original, o sonar poco natural, etc. 🤖
Puedes mejorar esta traducciónayudándonos a guiar mejor al LLM de IA.
La documentación de la API utilizaSwagger UI yReDoc, y cada uno de estos necesita algunos archivos JavaScript y CSS.
Por defecto, esos archivos se sirven desde unCDN.
Pero es posible personalizarlo, puedes establecer un CDN específico, o servir los archivos tú mismo.
CDN Personalizado para JavaScript y CSS¶
Digamos que quieres usar unCDN diferente, por ejemplo, quieres usarhttps://unpkg.com/.
Esto podría ser útil si, por ejemplo, vives en un país que restringe algunas URLs.
Desactiva la documentación automática¶
El primer paso es desactivar la documentación automática, ya que por defecto, esos usan el CDN por defecto.
Para desactivarlos, establece sus URLs enNone cuando crees tu aplicación deFastAPI:
fromfastapiimportFastAPIfromfastapi.openapi.docsimport(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)asyncdefcustom_swagger_ui_html():returnget_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)asyncdefswagger_ui_redirect():returnget_swagger_ui_oauth2_redirect_html()@app.get("/redoc",include_in_schema=False)asyncdefredoc_html():returnget_redoc_html(openapi_url=app.openapi_url,title=app.title+" - ReDoc",redoc_js_url="https://unpkg.com/redoc@2/bundles/redoc.standalone.js",)@app.get("/users/{username}")asyncdefread_user(username:str):return{"message":f"Hello{username}"}Incluye la documentación personalizada¶
Ahora puedes crear laspath operations para la documentación personalizada.
Puedes reutilizar las funciones internas de FastAPI para crear las páginas HTML para la documentación, y pasarles los argumentos necesarios:
openapi_url: la URL donde la página HTML para la documentación puede obtener el OpenAPI esquema de tu API. Puedes usar aquí el atributoapp.openapi_url.title: el título de tu API.oauth2_redirect_url: puedes usarapp.swagger_ui_oauth2_redirect_urlaquí para usar el valor por defecto.swagger_js_url: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivoJavaScript. Esta es la URL personalizada del CDN.swagger_css_url: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivoCSS. Esta es la URL personalizada del CDN.
Y de manera similar para ReDoc...
fromfastapiimportFastAPIfromfastapi.openapi.docsimport(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)asyncdefcustom_swagger_ui_html():returnget_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)asyncdefswagger_ui_redirect():returnget_swagger_ui_oauth2_redirect_html()@app.get("/redoc",include_in_schema=False)asyncdefredoc_html():returnget_redoc_html(openapi_url=app.openapi_url,title=app.title+" - ReDoc",redoc_js_url="https://unpkg.com/redoc@2/bundles/redoc.standalone.js",)@app.get("/users/{username}")asyncdefread_user(username:str):return{"message":f"Hello{username}"}Consejo
Lapath operation paraswagger_ui_redirect es una herramienta cuando utilizas OAuth2.
Si integras tu API con un proveedor OAuth2, podrás autenticarte y regresar a la documentación de la API con las credenciales adquiridas. E interactuar con ella usando la autenticación real de OAuth2.
Swagger UI lo manejará detrás de escena para ti, pero necesita este auxiliar de "redirección".
Crea unapath operation para probarlo¶
Ahora, para poder probar que todo funciona, crea unapath operation:
fromfastapiimportFastAPIfromfastapi.openapi.docsimport(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)asyncdefcustom_swagger_ui_html():returnget_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)asyncdefswagger_ui_redirect():returnget_swagger_ui_oauth2_redirect_html()@app.get("/redoc",include_in_schema=False)asyncdefredoc_html():returnget_redoc_html(openapi_url=app.openapi_url,title=app.title+" - ReDoc",redoc_js_url="https://unpkg.com/redoc@2/bundles/redoc.standalone.js",)@app.get("/users/{username}")asyncdefread_user(username:str):return{"message":f"Hello{username}"}Pruébalo¶
Ahora, deberías poder ir a tu documentación enhttp://127.0.0.1:8000/docs, y recargar la página, cargará esos recursos desde el nuevo CDN.
self hosting de JavaScript y CSS para la documentación¶
El self hosting de JavaScript y CSS podría ser útil si, por ejemplo, necesitas que tu aplicación siga funcionando incluso offline, sin acceso a Internet, o en una red local.
Aquí verás cómo servir esos archivos tú mismo, en la misma aplicación de FastAPI, y configurar la documentación para usarla.
Estructura de archivos del proyecto¶
Supongamos que la estructura de archivos de tu proyecto se ve así:
.├── app│ ├── __init__.py│ ├── main.pyAhora crea un directorio para almacenar esos archivos estáticos.
Tu nueva estructura de archivos podría verse así:
.├── app│ ├── __init__.py│ ├── main.py└── static/Descarga los archivos¶
Descarga los archivos estáticos necesarios para la documentación y ponlos en ese directoriostatic/.
Probablemente puedas hacer clic derecho en cada enlace y seleccionar una opción similar aGuardar enlace como....
Swagger UI utiliza los archivos:
YReDoc utiliza el archivo:
Después de eso, tu estructura de archivos podría verse así:
.├── app│ ├── __init__.py│ ├── main.py└── static ├── redoc.standalone.js ├── swagger-ui-bundle.js └── swagger-ui.cssSirve los archivos estáticos¶
- Importa
StaticFiles. - "Monta" una instance de
StaticFiles()en un path específico.
fromfastapiimportFastAPIfromfastapi.openapi.docsimport(get_redoc_html,get_swagger_ui_html,get_swagger_ui_oauth2_redirect_html,)fromfastapi.staticfilesimportStaticFilesapp=FastAPI(docs_url=None,redoc_url=None)app.mount("/static",StaticFiles(directory="static"),name="static")@app.get("/docs",include_in_schema=False)asyncdefcustom_swagger_ui_html():returnget_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)asyncdefswagger_ui_redirect():returnget_swagger_ui_oauth2_redirect_html()@app.get("/redoc",include_in_schema=False)asyncdefredoc_html():returnget_redoc_html(openapi_url=app.openapi_url,title=app.title+" - ReDoc",redoc_js_url="/static/redoc.standalone.js",)@app.get("/users/{username}")asyncdefread_user(username:str):return{"message":f"Hello{username}"}Prueba los archivos estáticos¶
Inicia tu aplicación y ve ahttp://127.0.0.1:8000/static/redoc.standalone.js.
Deberías ver un archivo JavaScript muy largo deReDoc.
Podría comenzar con algo como:
/*! For license information please see redoc.standalone.js.LICENSE.txt */!function(e,t){"object"==typeofexports&&"object"==typeofmodule?module.exports=t(require("null")):...Eso confirma que puedes servir archivos estáticos desde tu aplicación, y que colocaste los archivos estáticos para la documentación en el lugar correcto.
Ahora podemos configurar la aplicación para usar esos archivos estáticos para la documentación.
Desactiva la documentación automática para archivos estáticos¶
Igual que cuando usas un CDN personalizado, el primer paso es desactivar la documentación automática, ya que esos usan el CDN por defecto.
Para desactivarlos, establece sus URLs enNone cuando crees tu aplicación deFastAPI:
fromfastapiimportFastAPIfromfastapi.openapi.docsimport(get_redoc_html,get_swagger_ui_html,get_swagger_ui_oauth2_redirect_html,)fromfastapi.staticfilesimportStaticFilesapp=FastAPI(docs_url=None,redoc_url=None)app.mount("/static",StaticFiles(directory="static"),name="static")@app.get("/docs",include_in_schema=False)asyncdefcustom_swagger_ui_html():returnget_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)asyncdefswagger_ui_redirect():returnget_swagger_ui_oauth2_redirect_html()@app.get("/redoc",include_in_schema=False)asyncdefredoc_html():returnget_redoc_html(openapi_url=app.openapi_url,title=app.title+" - ReDoc",redoc_js_url="/static/redoc.standalone.js",)@app.get("/users/{username}")asyncdefread_user(username:str):return{"message":f"Hello{username}"}Incluye la documentación personalizada para archivos estáticos¶
Y de la misma manera que con un CDN personalizado, ahora puedes crear laspath operations para la documentación personalizada.
Nuevamente, puedes reutilizar las funciones internas de FastAPI para crear las páginas HTML para la documentación, y pasarles los argumentos necesarios:
openapi_url: la URL donde la página HTML para la documentación puede obtener el OpenAPI esquema de tu API. Puedes usar aquí el atributoapp.openapi_url.title: el título de tu API.oauth2_redirect_url: puedes usarapp.swagger_ui_oauth2_redirect_urlaquí para usar el valor por defecto.swagger_js_url: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivoJavaScript.Este es el que tu propia aplicación está sirviendo ahora.swagger_css_url: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivoCSS.Este es el que tu propia aplicación está sirviendo ahora.
Y de manera similar para ReDoc...
fromfastapiimportFastAPIfromfastapi.openapi.docsimport(get_redoc_html,get_swagger_ui_html,get_swagger_ui_oauth2_redirect_html,)fromfastapi.staticfilesimportStaticFilesapp=FastAPI(docs_url=None,redoc_url=None)app.mount("/static",StaticFiles(directory="static"),name="static")@app.get("/docs",include_in_schema=False)asyncdefcustom_swagger_ui_html():returnget_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)asyncdefswagger_ui_redirect():returnget_swagger_ui_oauth2_redirect_html()@app.get("/redoc",include_in_schema=False)asyncdefredoc_html():returnget_redoc_html(openapi_url=app.openapi_url,title=app.title+" - ReDoc",redoc_js_url="/static/redoc.standalone.js",)@app.get("/users/{username}")asyncdefread_user(username:str):return{"message":f"Hello{username}"}Consejo
Lapath operation paraswagger_ui_redirect es una herramienta cuando utilizas OAuth2.
Si integras tu API con un proveedor OAuth2, podrás autenticarte y regresar a la documentación de la API con las credenciales adquiridas. Y interactuar con ella usando la autenticación real de OAuth2.
Swagger UI lo manejará detrás de escena para ti, pero necesita este auxiliar de "redirección".
Crea unapath operation para probar archivos estáticos¶
Ahora, para poder probar que todo funciona, crea unapath operation:
fromfastapiimportFastAPIfromfastapi.openapi.docsimport(get_redoc_html,get_swagger_ui_html,get_swagger_ui_oauth2_redirect_html,)fromfastapi.staticfilesimportStaticFilesapp=FastAPI(docs_url=None,redoc_url=None)app.mount("/static",StaticFiles(directory="static"),name="static")@app.get("/docs",include_in_schema=False)asyncdefcustom_swagger_ui_html():returnget_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)asyncdefswagger_ui_redirect():returnget_swagger_ui_oauth2_redirect_html()@app.get("/redoc",include_in_schema=False)asyncdefredoc_html():returnget_redoc_html(openapi_url=app.openapi_url,title=app.title+" - ReDoc",redoc_js_url="/static/redoc.standalone.js",)@app.get("/users/{username}")asyncdefread_user(username:str):return{"message":f"Hello{username}"}Prueba la UI de Archivos Estáticos¶
Ahora, deberías poder desconectar tu WiFi, ir a tu documentación enhttp://127.0.0.1:8000/docs, y recargar la página.
E incluso sin Internet, podrás ver la documentación de tu API e interactuar con ella.