Movatterモバイル変換

[0]ホーム
URL:

Saltar a contenido
Join theFastAPI Cloud waiting list 🚀
Follow@fastapi onX (Twitter) to stay updated
FollowFastAPI onLinkedIn to stay updated
Subscribe to theFastAPI and friends newsletter 🎉
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor
sponsor

Configurar Swagger UI

🌐 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.

Versión en inglés

Puedes configurar algunosparámetros adicionales de Swagger UI.

Para configurarlos, pasa el argumentoswagger_ui_parameters al crear el objeto de la appFastAPI() o a la funciónget_swagger_ui_html().

swagger_ui_parameters recibe un diccionario con las configuraciones pasadas directamente a Swagger UI.

FastAPI convierte las configuraciones aJSON para hacerlas compatibles con JavaScript, ya que eso es lo que Swagger UI necesita.

Desactivar el resaltado de sintaxis

Por ejemplo, podrías desactivar el resaltado de sintaxis en Swagger UI.

Sin cambiar la configuración, el resaltado de sintaxis está activado por defecto:

Pero puedes desactivarlo estableciendosyntaxHighlight enFalse:

fromfastapiimportFastAPIapp=FastAPI(swagger_ui_parameters={"syntaxHighlight":False})@app.get("/users/{username}")asyncdefread_user(username:str):return{"message":f"Hello{username}"}

...y entonces Swagger UI ya no mostrará el resaltado de sintaxis:

Cambiar el tema

De la misma manera, podrías configurar el tema del resaltado de sintaxis con la clave"syntaxHighlight.theme" (ten en cuenta que tiene un punto en el medio):

fromfastapiimportFastAPIapp=FastAPI(swagger_ui_parameters={"syntaxHighlight":{"theme":"obsidian"}})@app.get("/users/{username}")asyncdefread_user(username:str):return{"message":f"Hello{username}"}

Esa configuración cambiaría el tema de color del resaltado de sintaxis:

Cambiar los parámetros por defecto de Swagger UI

FastAPI incluye algunos parámetros de configuración por defecto apropiados para la mayoría de los casos de uso.

Incluye estas configuraciones por defecto:

# Code above omitted 👆dict[str,Any],Doc("""        Default configurations for Swagger UI.        You can use it as a template to add any other configurations needed.        """),]={"dom_id":"#swagger-ui","layout":"BaseLayout","deepLinking":True,"showExtensions":True,"showCommonExtensions":True,}# Code below omitted 👇
👀 Full file preview
importjsonfromtypingimportAnnotated,Anyfromannotated_docimportDocfromfastapi.encodersimportjsonable_encoderfromstarlette.responsesimportHTMLResponseswagger_ui_default_parameters:Annotated[dict[str,Any],Doc("""        Default configurations for Swagger UI.        You can use it as a template to add any other configurations needed.        """),]={"dom_id":"#swagger-ui","layout":"BaseLayout","deepLinking":True,"showExtensions":True,"showCommonExtensions":True,}defget_swagger_ui_html(*,openapi_url:Annotated[str,Doc("""            The OpenAPI URL that Swagger UI should load and use.            This is normally done automatically by FastAPI using the default URL            `/openapi.json`.            Read more about it in the            [FastAPI docs for Conditional OpenAPI](https://fastapi.tiangolo.com/how-to/conditional-openapi/#conditional-openapi-from-settings-and-env-vars)            """),],title:Annotated[str,Doc("""            The HTML `<title>` content, normally shown in the browser tab.            Read more about it in the            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)            """),],swagger_js_url:Annotated[str,Doc("""            The URL to use to load the Swagger UI JavaScript.            It is normally set to a CDN URL.            Read more about it in the            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)            """),]="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",swagger_css_url:Annotated[str,Doc("""            The URL to use to load the Swagger UI CSS.            It is normally set to a CDN URL.            Read more about it in the            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)            """),]="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",swagger_favicon_url:Annotated[str,Doc("""            The URL of the favicon to use. It is normally shown in the browser tab.            """),]="https://fastapi.tiangolo.com/img/favicon.png",oauth2_redirect_url:Annotated[str|None,Doc("""            The OAuth2 redirect URL, it is normally automatically handled by FastAPI.            Read more about it in the            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)            """),]=None,init_oauth:Annotated[dict[str,Any]|None,Doc("""            A dictionary with Swagger UI OAuth2 initialization configurations.            Read more about the available configuration options in the            [Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).            """),]=None,swagger_ui_parameters:Annotated[dict[str,Any]|None,Doc("""            Configuration parameters for Swagger UI.            It defaults to [swagger_ui_default_parameters][fastapi.openapi.docs.swagger_ui_default_parameters].            Read more about it in the            [FastAPI docs about how to Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/).            """),]=None,)->HTMLResponse:"""    Generate and return the HTML  that loads Swagger UI for the interactive    API docs (normally served at `/docs`).    You would only call this function yourself if you needed to override some parts,    for example the URLs to use to load Swagger UI's JavaScript and CSS.    Read more about it in the    [FastAPI docs for Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/)    and the [FastAPI docs for Custom Docs UI Static Assets (Self-Hosting)](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/).    """current_swagger_ui_parameters=swagger_ui_default_parameters.copy()ifswagger_ui_parameters:current_swagger_ui_parameters.update(swagger_ui_parameters)html=f"""    <!DOCTYPE html>    <html>    <head>    <meta name="viewport" content="width=device-width, initial-scale=1.0">    <link type="text/css" rel="stylesheet" href="{swagger_css_url}">    <link rel="shortcut icon" href="{swagger_favicon_url}">    <title>{title}</title>    </head>    <body>    <div id="swagger-ui">    </div>    <script src="{swagger_js_url}"></script>    <!-- `SwaggerUIBundle` is now available on the page -->    <script>    const ui = SwaggerUIBundle({{        url: '{openapi_url}',    """forkey,valueincurrent_swagger_ui_parameters.items():html+=f"{json.dumps(key)}:{json.dumps(jsonable_encoder(value))},\n"ifoauth2_redirect_url:html+=f"oauth2RedirectUrl: window.location.origin + '{oauth2_redirect_url}',"html+="""    presets: [        SwaggerUIBundle.presets.apis,        SwaggerUIBundle.SwaggerUIStandalonePreset        ],    })"""ifinit_oauth:html+=f"""        ui.initOAuth({json.dumps(jsonable_encoder(init_oauth))})        """html+="""    </script>    </body>    </html>    """returnHTMLResponse(html)defget_redoc_html(*,openapi_url:Annotated[str,Doc("""            The OpenAPI URL that ReDoc should load and use.            This is normally done automatically by FastAPI using the default URL            `/openapi.json`.            Read more about it in the            [FastAPI docs for Conditional OpenAPI](https://fastapi.tiangolo.com/how-to/conditional-openapi/#conditional-openapi-from-settings-and-env-vars)            """),],title:Annotated[str,Doc("""            The HTML `<title>` content, normally shown in the browser tab.            Read more about it in the            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)            """),],redoc_js_url:Annotated[str,Doc("""            The URL to use to load the ReDoc JavaScript.            It is normally set to a CDN URL.            Read more about it in the            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)            """),]="https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js",redoc_favicon_url:Annotated[str,Doc("""            The URL of the favicon to use. It is normally shown in the browser tab.            """),]="https://fastapi.tiangolo.com/img/favicon.png",with_google_fonts:Annotated[bool,Doc("""            Load and use Google Fonts.            """),]=True,)->HTMLResponse:"""    Generate and return the HTML response that loads ReDoc for the alternative    API docs (normally served at `/redoc`).    You would only call this function yourself if you needed to override some parts,    for example the URLs to use to load ReDoc's JavaScript and CSS.    Read more about it in the    [FastAPI docs for Custom Docs UI Static Assets (Self-Hosting)](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/).    """html=f"""    <!DOCTYPE html>    <html>    <head>    <title>{title}</title>    <!-- needed for adaptive design -->    <meta charset="utf-8"/>    <meta name="viewport" content="width=device-width, initial-scale=1">    """ifwith_google_fonts:html+="""    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">    """html+=f"""    <link rel="shortcut icon" href="{redoc_favicon_url}">    <!--    ReDoc doesn't change outer page styles    -->    <style>      body{{        margin: 0;        padding: 0;}}    </style>    </head>    <body>    <noscript>        ReDoc requires Javascript to function. Please enable it to browse the documentation.    </noscript>    <redoc spec-url="{openapi_url}"></redoc>    <script src="{redoc_js_url}"> </script>    </body>    </html>    """returnHTMLResponse(html)defget_swagger_ui_oauth2_redirect_html()->HTMLResponse:"""    Generate the HTML response with the OAuth2 redirection for Swagger UI.    You normally don't need to use or change this.    """# copied from https://github.com/swagger-api/swagger-ui/blob/v4.14.0/dist/oauth2-redirect.htmlhtml="""    <!doctype html>    <html lang="en-US">    <head>        <title>Swagger UI: OAuth2 Redirect</title>    </head>    <body>    <script>        'use strict';        function run () {            var oauth2 = window.opener.swaggerUIRedirectOauth2;            var sentState = oauth2.state;            var redirectUrl = oauth2.redirectUrl;            var isValid, qp, arr;            if (/code|token|error/.test(window.location.hash)) {                qp = window.location.hash.substring(1).replace('?', '&');            } else {                qp = location.search.substring(1);            }            arr = qp.split("&");            arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';});            qp = qp ? JSON.parse('{' + arr.join() + '}',                    function (key, value) {                        return key === "" ? value : decodeURIComponent(value);                    }            ) :{};            isValid = qp.state === sentState;            if ((              oauth2.auth.schema.get("flow") === "accessCode" ||              oauth2.auth.schema.get("flow") === "authorizationCode" ||              oauth2.auth.schema.get("flow") === "authorization_code"            ) && !oauth2.auth.code) {                if (!isValid) {                    oauth2.errCb({                        authId: oauth2.auth.name,                        source: "auth",                        level: "warning",                        message: "Authorization may be unsafe, passed state was changed in server. The passed state wasn't returned from auth server."                    });                }                if (qp.code) {                    delete oauth2.state;                    oauth2.auth.code = qp.code;                    oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});                } else {                    let oauthErrorMsg;                    if (qp.error) {                        oauthErrorMsg = "["+qp.error+"]: " +                            (qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +                            (qp.error_uri ? "More info: "+qp.error_uri : "");                    }                    oauth2.errCb({                        authId: oauth2.auth.name,                        source: "auth",                        level: "error",                        message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server."                    });                }            } else {                oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});            }            window.close();        }        if (document.readyState !== 'loading') {            run();        } else {            document.addEventListener('DOMContentLoaded', function () {                run();            });        }    </script>    </body>    </html>        """returnHTMLResponse(content=html)

Puedes sobrescribir cualquiera de ellos estableciendo un valor diferente en el argumentoswagger_ui_parameters.

Por ejemplo, para desactivardeepLinking podrías pasar estas configuraciones aswagger_ui_parameters:

fromfastapiimportFastAPIapp=FastAPI(swagger_ui_parameters={"deepLinking":False})@app.get("/users/{username}")asyncdefread_user(username:str):return{"message":f"Hello{username}"}

Otros parámetros de Swagger UI

Para ver todas las demás configuraciones posibles que puedes usar, lee ladocumentación oficial de los parámetros de Swagger UI.

Configuraciones solo de JavaScript

Swagger UI también permite otras configuraciones que son objetossolo de JavaScript (por ejemplo, funciones de JavaScript).

FastAPI también incluye estas configuracionespresets solo de #"button" data-md-component="top" hidden> Volver al principio

[8]ページ先頭
©2009-2026 Movatter.jp