* `description`: un `str` con una breve descripción para la documentación externa.
    * `url` (**requerido**): un `str` con la URL para la documentación externa.

### Crear metadata para etiquetas

Probemos eso en un ejemplo con etiquetas para `users` y `items`.

Crea metadata para tus etiquetas y pásala al parámetro `openapi_tags`:

{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}

Como eles são parte da URL, eles são "naturalmente" strings.

Mas quando você declara eles com os tipos do Python (no exemplo acima, como `int`), eles são convertidos para aquele tipo e validados em relação a ele.

Todo o processo que era aplicado para parâmetros de rota também é aplicado para parâmetros de consulta:

* Suporte do editor (obviamente)
* <abbr title="convertendo uma string que vem de um request HTTP em um dado Python">"Parsing"</abbr> de dados

En estos casos, puedes usar `root_path` para configurar tu aplicación.

El `root_path` es un mecanismo proporcionado por la especificación ASGI (en la que está construido FastAPI, a través de Starlette).

El `root_path` se usa para manejar estos casos específicos.

Y también se usa internamente al montar subaplicaciones.

También puedes crear una variable de entorno solo para una **invocación específica de un programa**, que está disponible solo para ese programa, y solo durante su duración.

Para hacer eso, créala justo antes del programa en sí, en la misma línea:

<div class="termy">

```console

No obstante, podrías tener un caso de uso muy específico donde realmente necesites desactivar la documentación de la API para algún entorno (por ejemplo, para producción) o dependiendo de configuraciones de variables de entorno.

## OpenAPI condicional desde configuraciones y variables de entorno

Puedes usar fácilmente las mismas configuraciones de Pydantic para configurar tu OpenAPI generado y las interfaces de usuario de la documentación.

Por ejemplo:

**FastAPI** proporciona los mismos `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette.

Y como el `Response` se puede usar frecuentemente para establecer headers y cookies, **FastAPI** también lo proporciona en `fastapi.Response`.

///

# Testando WebSockets

Você pode usar o mesmo `TestClient` para testar WebSockets.

Para isso, você utiliza o `TestClient` dentro de uma instrução `with`, conectando com o WebSocket:

{* ../../docs_src/app_testing/tutorial002.py hl[27:31] *}

/// note | Nota

Para mais detalhes, confira a documentação do Starlette para <a href="https://www.starlette.io/testclient/#testing-websocket-sessions" class="external-link" target="_blank">testar WebSockets</a>.

Isso é útil se você não souber os nomes de campo / atributo válidos (que seriam necessários para um modelo Pydantic) antecipadamente.

Neste caso, você pode usar `typing.Dict` (ou simplesmente dict no Python 3.9 e superior):

{* ../../docs_src/extra_models/tutorial005.py hl[1,8] *}

## Em resumo

Use vários modelos Pydantic e herde livremente para cada caso.

Como parte de la creación del objeto de la aplicación, se registra una *path operation* para `/openapi.json` (o para lo que sea que configures tu `openapi_url`).

Simplemente devuelve un response JSON con el resultado del método `.openapi()` de la aplicación.

Por defecto, lo que hace el método `.openapi()` es revisar la propiedad `.openapi_schema` para ver si tiene contenido y devolverlo.

</blockquote>

## Investigação

Ao usar todas as alternativas anteriores, eu tive a chance de aprender com todas elas, aproveitar ideias e combiná-las da melhor maneira que encontrei para mim e para os times de desenvolvedores com os quais trabalhava.

Por exemplo, estava claro que idealmente ele deveria ser baseado nos _type hints_ padrões do Python.

Também, a melhor abordagem era usar padrões já existentes.