Cada página de operação leva um cliente: escolher um servidor, preencher os
parâmetros, editar o corpo, enviar.

## Nunca um proxy

O pedido é feito pelo navegador do leitor com `fetch`, direito ao servidor que ele
escolheu. Nada passa pelo site que serve a documentação.

É uma decisão, não uma limitação. Um proxy significaria que as credenciais do
leitor viajam para um terceiro — e o site de documentação é um terceiro para a API
que documenta. O preço é que uma API sem CORS não pode ser chamada daqui; o cliente
di-lo em vez de falhar em silêncio.

## Servidores

Cada servidor que o documento declara, com as suas variáveis como campos. Uma
operação que substitui `servers` obtém a sua própria lista.

## Autenticação

Um campo por esquema que o requisito da operação nomeie.

| Esquema                            | O que o cliente faz                                            |
| :--------------------------------- | :------------------------------------------------------------- |
| `apiKey` em cabeçalho ou query     | Envia o valor onde o documento diz                             |
| `http` `bearer`                    | Pede o token, envia `Authorization: Bearer …`                  |
| `http` `basic`                     | Pede utilizador e senha, codifica-os                           |
| `oauth2`, `openIdConnect`          | Pede o token — ambos acabam num cabeçalho bearer               |
| `apiKey` em cookie                 | **Diz que não pode.** Uma página não pode pôr um cookie        |
| `mutualTLS`                        | **Diz que não pode.** Uma página não tem certificado cliente   |

> [!IMPORTANT]
> O que escreves num campo de autenticação fica neste separador, nunca é
> guardado, e é enviado apenas ao servidor que escolheste.

Um parâmetro de cookie deliberadamente **não** é construído no pedido. `Cookie` é
um nome de cabeçalho proibido para o `fetch`: um navegador descarta-o sem erro e
sem nada na consola, por isso o pedido teria ficado em silêncio sem a credencial
enquanto a amostra `curl` ao lado mostrava o cabeçalho presente — o único lugar
onde um leitor vai confirmar. O cliente diz em vez disso que o cookie não pode ser
posto a partir de uma página, para que o enviado e o mostrado voltem a ser o mesmo
pedido.

### Um valor para começar

Um esquema pode nomear um, e o cliente preenche o campo com ele:

```yaml [openapi.yaml]
securitySchemes:
  bearer:
    type: http
    scheme: bearer
    x-duxt-example: demo-token
```

Uma extensão, porque o OpenAPI não tem um campo para isto: um esquema de
segurança diz onde vai uma credencial, nunca com que se parece. É a diferença
entre ver um cliente e vê-lo funcionar — um endpoint de demonstração que responde
a qualquer token pode dizê-lo, em vez de pedir que se invente um valor primeiro.

> [!CAUTION]
> Um ficheiro publicado. Aqui vai um valor de demonstração, nunca uma credencial
> real.

## O corpo

Duas vistas do mesmo valor, e o leitor escolhe uma vez para todo o site:

- **Formulário** — um campo por propriedade, desenhado a partir do esquema, com as
  restrições que declara.
- **JSON** — um editor, para um corpo que o formulário não consegue desenhar. Um
  corpo que ainda não é JSON válido é enviado tal como escrito em vez de bloqueado.

Um esquema demasiado solto para ser desenhado como formulário di-lo e oferece o
editor.

O editor é o CodeMirror, carregado a pedido — uma página sem endpoint não descarrega
nada dele. Deliberadamente não é o Monaco: um editor cujos workers e megabytes
cada site consumidor carrega, para uma caixa com dez linhas de JSON, é a troca
errada para um pacote.

## A resposta

Estado, cabeçalhos e corpo, sob o editor. É também por isso que as amostras de
código ao lado param no pedido — ver
[Amostras de pedido](/reference/openapi/request-samples).

## Quando não chega

O `fetch` rejeita com um `TypeError` nu tanto para uma recusa de CORS como para
uma falha de DNS ou uma rede em baixo, por isso o cliente não pode dizer ao leitor
qual dos três foi. Diz que o pedido não chegou ao servidor, e nomeia as duas razões
prováveis, em vez de adivinhar uma.

## Limites do pedido

Pode cancelar um pedido pendente. Sair da operação também o cancela. O limite de 30 segundos inclui um corpo de resposta bloqueado. A pré-visualização conserva no máximo 1 MiB e indica cortes. As credenciais ficam apenas no componente atual, sem armazenamento adicional nem proxy.