El cliente de pruebas
Una petición real, enviada por el propio navegador del lector.
Cada página de operación lleva un cliente: elige un servidor, rellena los parámetros, edita el cuerpo, envíalo.
Nunca un proxy
La petición la hace el navegador del lector con fetch, directa al servidor que
eligió. Nada pasa por el sitio que sirve la documentación.
Es una decisión, no una limitación. Un proxy significaría que las credenciales del lector viajan a un tercero — y el sitio de documentación es un tercero para la API que documenta. El coste es que una API sin CORS no puede llamarse desde aquí; el cliente lo dice en lugar de fallar en silencio.
Servidores
Cada servidor que declara el documento, con sus variables como campos. Una
operación que sobrescribe servers obtiene su propia lista.
Autenticación
Un campo por esquema que nombre el requisito de la operación.
| Esquema | Qué hace el cliente |
|---|---|
apiKey en cabecera o consulta | Envía el valor donde dice el documento |
http bearer | Pide el token, envía Authorization: Bearer … |
http basic | Pide usuario y contraseña, los codifica |
oauth2, openIdConnect | Pide el token — ambos acaban en una cabecera bearer |
apiKey en cookie | Dice que no puede. Una página no puede fijar una cookie |
mutualTLS | Dice que no puede. Una página no tiene certificado cliente |
!IMPORTANT Lo que escribes en un campo de autenticación se queda en esta pestaña, nunca se almacena, y solo se envía al servidor que elegiste.
Un parámetro de cookie deliberadamente no se construye en la petición.
Cookie es un nombre de cabecera prohibido para fetch: el navegador la descarta
sin error y sin nada en la consola, así que la petición carecería en silencio de la
credencial mientras la muestra de curl al lado mostraba la cabecera presente —
el único lugar donde un lector mira para confirmarlo. El cliente dice en cambio
que la cookie no puede fijarse desde una página, de modo que lo enviado y lo
mostrado vuelven a ser la misma petición.
Un valor para empezar
Un esquema puede nombrar uno, y el cliente rellena el campo con él:
securitySchemes:
bearer:
type: http
scheme: bearer
x-duxt-example: demo-token
Una extensión, porque OpenAPI no tiene un campo para esto: un esquema de seguridad dice dónde va una credencial, nunca qué aspecto tiene. Es la diferencia entre ver un cliente y verlo funcionar: un endpoint de demostración que responde a cualquier token puede decirlo, en vez de pedir que se invente un valor primero.
!CAUTION Un archivo publicado. Aquí va un valor de demostración, nunca una credencial real.
El cuerpo
Dos vistas del mismo valor, y el lector elige una vez para todo el sitio:
- Formulario — un campo por propiedad, dibujado desde el esquema, con las restricciones que declara.
- JSON — un editor, para un cuerpo que el formulario no puede dibujar. Un cuerpo que todavía no es JSON válido se envía tal cual en lugar de bloquearse.
Un esquema demasiado laxo para dibujarse como formulario lo dice y ofrece el editor.
El editor es CodeMirror, cargado a demanda — una página sin endpoint no descarga nada de él. Deliberadamente no es Monaco: un editor cuyos workers y megabytes carga cada sitio consumidor, para una caja con diez líneas de JSON, es el trato equivocado para un paquete.
La respuesta
Estado, cabeceras y cuerpo, bajo el editor. Por eso también las muestras de código al lado se detienen en la petición — ver Muestras de peticiones.
Cuando no llega
fetch rechaza con un TypeError desnudo tanto para un rechazo de CORS como para
un fallo de DNS o una red caída, así que el cliente no puede decirle al lector cuál
de los tres fue. Dice que la petición no llegó al servidor, y nombra las dos
razones probables, en lugar de adivinar una.