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:
Parámetro
Tipo
Descripción
title
str
El título de la API.
summary
str
Un resumen corto de la API. Disponible desde OpenAPI 3.1.0, FastAPI 0.99.0.
description
str
Una breve descripción de la API. Puede usar Markdown.
version
string
La versión de la API. Esta es la versión de tu propia aplicación, no de OpenAPI. Por ejemplo, 2.5.0.
terms_of_service
str
Una URL a los Términos de Servicio para la API. Si se proporciona, debe ser una URL.
contact
dict
La información de contacto para la API expuesta. Puede contener varios campos. contact fields
Parámetro
Tipo
Descripción
name
str
El nombre identificativo de la persona/organización de contacto.
url
str
La URL que apunta a la información de contacto. DEBE tener el formato de una URL.
email
str
La dirección de correo electrónico de la persona/organización de contacto. DEBE tener el formato de una dirección de correo.
license_info
dict
La información de la licencia para la API expuesta. Puede contener varios campos. license_info fields
Parámetro
Tipo
Descripción
name
str
REQUERIDO (si se establece un license_info). El nombre de la licencia utilizada para la API.
identifier
str
Una expresión de licencia SPDX para la API. El campo identifier es mutuamente excluyente del campo url. Disponible desde OpenAPI 3.1.0, FastAPI 0.99.0.
url
str
Una URL a la licencia utilizada para la API. DEBE tener el formato de una URL.
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"}]
Consejo
Puedes escribir Markdown en el campo description y se mostrará en el resultado.
Con esta configuración, la documentación automática de la API se vería así:
Desde OpenAPI 3.1.0 y FastAPI 0.99.0, también puedes establecer la license_info con un identifier en lugar de una url.
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":"MIT",},)@app.get("/items/")asyncdefread_items():return[{"name":"Katana"}]
Probemos eso en un ejemplo con etiquetas para users y items.
Crea metadata para tus etiquetas y pásala al parámetro openapi_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).
Consejo
No tienes que agregar metadata para todas las etiquetas que uses.
Usa el parámetro tags con tus path operations (y APIRouters) 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"}]
El orden de cada diccionario de metadata de etiqueta también define el orden mostrado en la interfaz de documentación.
Por ejemplo, aunque users iría después de items en orden alfabético, se muestra antes porque agregamos su metadata como el primer diccionario en la list.
Si quieres deshabilitar el esquema OpenAPI completamente, puedes establecer openapi_url=None, eso también deshabilitará las interfaces de usuario de documentación que lo usan.