Le client d’essai
Une vraie requête, envoyée par le navigateur du lecteur lui-même.
Chaque page d’opération porte un client : choisir un serveur, remplir les paramètres, éditer le corps, envoyer.
Jamais de proxy
La requête est faite par le navigateur du lecteur avec fetch, droit vers le
serveur qu’il a choisi. Rien ne passe par le site qui sert la documentation.
C’est une décision, pas une limitation. Un proxy signifierait que les identifiants du lecteur voyagent vers un tiers — et le site de documentation est un tiers pour l’API qu’il documente. Le prix, c’est qu’une API sans CORS ne peut pas être appelée d’ici ; le client le dit au lieu d’échouer en silence.
Serveurs
Chaque serveur que le document déclare, avec ses variables en champs. Une
opération qui surcharge servers obtient sa propre liste.
Authentification
Un champ par schéma que nomme l’exigence de l’opération.
| Schéma | Ce que fait le client |
|---|---|
apiKey en en-tête ou en requête | Envoie la valeur là où le document le dit |
http bearer | Demande le jeton, envoie Authorization: Bearer … |
http basic | Demande utilisateur et mot de passe, les encode |
oauth2, openIdConnect | Demande le jeton — les deux finissent en en-tête bearer |
apiKey en cookie | Dit qu’il ne peut pas. Une page ne peut poser de cookie |
mutualTLS | Dit qu’il ne peut pas. Une page n’a pas de certificat |
!IMPORTANT Ce que vous tapez dans un champ d’authentification reste dans cet onglet, n’est jamais stocké, et n’est envoyé qu’au serveur que vous avez choisi.
Un paramètre de cookie n’est délibérément pas construit dans la requête.
Cookie est un nom d’en-tête interdit pour fetch : un navigateur le jette sans
erreur et sans rien en console, la requête aurait donc silencieusement manqué
l’identifiant tandis que l’échantillon curl à côté montrait l’en-tête présent —
le seul endroit où un lecteur regarde pour le vérifier. Le client dit plutôt que
le cookie ne peut pas être posé depuis une page, de sorte que ce qui est envoyé et
ce qui est montré redeviennent la même requête.
Une valeur pour commencer
Un schéma peut en nommer une, et le client remplit le champ avec :
securitySchemes:
bearer:
type: http
scheme: bearer
x-duxt-example: demo-token
Une extension, car OpenAPI n’a pas de champ pour cela : un schéma de sécurité dit où va une information d’authentification, jamais à quoi elle ressemble. C’est la différence entre voir un client et le voir fonctionner — un endpoint de démonstration qui accepte n’importe quel jeton peut le dire, plutôt que de demander d’en inventer un.
!CAUTION Un fichier publié. Mettez-y une valeur de démonstration, jamais une vraie.
Le corps
Deux vues de la même valeur, et le lecteur choisit une fois pour tout le site :
- Formulaire — un champ par propriété, dessiné depuis le schéma, avec les contraintes qu’il déclare.
- JSON — un éditeur, pour un corps que le formulaire ne peut pas dessiner. Un corps qui n’est pas encore du JSON valide est envoyé tel qu’écrit plutôt que bloqué.
Un schéma trop lâche pour être dessiné en formulaire le dit et propose l’éditeur.
L’éditeur est CodeMirror, chargé à la demande — une page sans endpoint n’en télécharge rien. Ce n’est délibérément pas Monaco : un éditeur dont chaque site consommateur porte les workers et les mégaoctets, pour une boîte qui contient dix lignes de JSON, est le mauvais compromis pour un paquet.
La réponse
Statut, en-têtes et corps, sous l’éditeur. C’est aussi pourquoi les échantillons de code à côté s’arrêtent à la requête — voir Échantillons de requête.
Quand elle n’arrive pas
fetch rejette avec un TypeError nu pour un refus CORS, un échec DNS et un
réseau absent pareillement, le client ne peut donc pas dire au lecteur lequel des
trois c’était. Il dit que la requête n’a pas atteint le serveur, et nomme les deux
raisons probables, plutôt que d’en deviner une.