Metadata y URLs de Docs¶

Puedes personalizar varias configuraciones de metadata en tu aplicaciónFastAPI.

Metadata para la API¶

Puedes establecer los siguientes campos que se usan en la especificación OpenAPI y en las interfaces automáticas de documentación de la API:

Puedes configurarlos de la siguiente manera:

fromfastapiimportFastAPIdescription="""ChimichangApp API helps you do awesome stuff. 🚀## ItemsYou can **read items**.## UsersYou will be able to:* **Create users** (_not implemented_).* **Read users** (_not implemented_)."""app=FastAPI(title="ChimichangApp",description=description,summary="Deadpool's favorite app. Nuff said.",version="0.0.1",terms_of_service="http://example.com/terms/",contact={"name":"Deadpoolio the Amazing","url":"http://x-force.example.com/contact/","email":"dp@x-force.example.com",},license_info={"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0.html",},)@app.get("/items/")asyncdefread_items():return[{"name":"Katana"}]

Con esta configuración, la documentación automática de la API se vería así:

Identificador de licencia¶

Desde OpenAPI 3.1.0 y FastAPI 0.99.0, también puedes establecer lalicense_info con unidentifier en lugar de unaurl.

Por ejemplo:

fromfastapiimportFastAPIdescription="""ChimichangApp API helps you do awesome stuff. 🚀## ItemsYou can **read items**.## UsersYou will be able to:* **Create users** (_not implemented_).* **Read users** (_not implemented_)."""app=FastAPI(title="ChimichangApp",description=description,summary="Deadpool's favorite app. Nuff said.",version="0.0.1",terms_of_service="http://example.com/terms/",contact={"name":"Deadpoolio the Amazing","url":"http://x-force.example.com/contact/","email":"dp@x-force.example.com",},license_info={"name":"Apache 2.0","identifier":"Apache-2.0",},)@app.get("/items/")asyncdefread_items():return[{"name":"Katana"}]

Metadata para etiquetas¶

También puedes agregar metadata adicional para las diferentes etiquetas usadas para agrupar tus path operations con el parámetroopenapi_tags.

Este toma una list que contiene un diccionario para cada etiqueta.

Cada diccionario puede contener:

• name (requerido): unstr con el mismo nombre de etiqueta que usas en el parámetrotags en tuspath operations yAPIRouters.
• description: unstr con una breve descripción de la etiqueta. Puede tener Markdown y se mostrará en la interfaz de documentación.
• externalDocs: undict que describe documentación externa con:
  • description: unstr con una breve descripción para la documentación externa.
  • url (requerido): unstr con la URL para la documentación externa.

Crear metadata para etiquetas¶

Probemos eso en un ejemplo con etiquetas parausers yitems.

Crea metadata para tus etiquetas y pásala al parámetroopenapi_tags:

fromfastapiimportFastAPItags_metadata=[{"name":"users","description":"Operations with users. The **login** logic is also here.",},{"name":"items","description":"Manage items. So _fancy_ they have their own docs.","externalDocs":{"description":"Items external docs","url":"https://fastapi.tiangolo.com/",},},]app=FastAPI(openapi_tags=tags_metadata)@app.get("/users/",tags=["users"])asyncdefget_users():return[{"name":"Harry"},{"name":"Ron"}]@app.get("/items/",tags=["items"])asyncdefget_items():return[{"name":"wand"},{"name":"flying broom"}]

Nota que puedes utilizar Markdown dentro de las descripciones, por ejemplo "login" se mostrará en negrita (login) y "fancy" se mostrará en cursiva (fancy).

Usar tus etiquetas¶

Usa el parámetrotags con tuspath operations (yAPIRouters) para asignarlas a diferentes etiquetas:

fromfastapiimportFastAPItags_metadata=[{"name":"users","description":"Operations with users. The **login** logic is also here.",},{"name":"items","description":"Manage items. So _fancy_ they have their own docs.","externalDocs":{"description":"Items external docs","url":"https://fastapi.tiangolo.com/",},},]app=FastAPI(openapi_tags=tags_metadata)@app.get("/users/",tags=["users"])asyncdefget_users():return[{"name":"Harry"},{"name":"Ron"}]@app.get("/items/",tags=["items"])asyncdefget_items():return[{"name":"wand"},{"name":"flying broom"}]

Revisa la documentación¶

Ahora, si revisas la documentación, mostrará toda la metadata adicional:

Orden de las etiquetas¶

El orden de cada diccionario de metadata de etiqueta también define el orden mostrado en la interfaz de documentación.

Por ejemplo, aunqueusers iría después deitems en orden alfabético, se muestra antes porque agregamos su metadata como el primer diccionario en la list.

URL de OpenAPI¶

Por defecto, el esquema OpenAPI se sirve en/openapi.json.

Pero puedes configurarlo con el parámetroopenapi_url.

Por ejemplo, para configurarlo para que se sirva en/api/v1/openapi.json:

fromfastapiimportFastAPIapp=FastAPI(openapi_url="/api/v1/openapi.json")@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]

Si quieres deshabilitar el esquema OpenAPI completamente, puedes estableceropenapi_url=None, eso también deshabilitará las interfaces de usuario de documentación que lo usan.

URLs de Docs¶

Puedes configurar las dos interfaces de usuario de documentación incluidas:

• Swagger UI: servida en/docs.
  • Puedes establecer su URL con el parámetrodocs_url.
  • Puedes deshabilitarla estableciendodocs_url=None.
• ReDoc: servida en/redoc.
  • Puedes establecer su URL con el parámetroredoc_url.
  • Puedes deshabilitarla estableciendoredoc_url=None.

Por ejemplo, para configurar Swagger UI para que se sirva en/documentation y deshabilitar ReDoc:

fromfastapiimportFastAPIapp=FastAPI(docs_url="/documentation",redoc_url=None)@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]