O cliente de ensaio
Um pedido real, enviado pelo próprio navegador do leitor.
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:
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.
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.