Documenter le contrat réel d’une API avec OpenAPI.
Une spécification API doit refléter le contrat réel, y compris erreurs et authentification. Signalez les comportements inconnus plutôt que d’inventer une description soignée.
Adaptez le processus à votre tâche.
Documentez l’endpoint, les paramètres, l’authentification et le contrat de réponse réels avec une version OpenAPI précisée. Incluez les erreurs connues et marquez l’inconnu au lieu de créer un contrat apparemment complet depuis des hypothèses.
- Ce que vous fournissez
- Descriptions vérifiées des endpoints et exemples de réponses.
- Ce que vous obtenez
- Ébauche OpenAPI avec contrats non résolus signalés.
Consultez les données et le résultat.
Entrée et sortie illustratives · exemple pédagogique, pas une exécution WebAct en direct
Exemple champ
Produce an OpenAPI 3.1.1 JSON fragment for fictional GET /items. Confirmed response: status 200, application/json array, each item requires string id and name. Authentication and errors are not specified.
Exemple complet
{
"openapi": "3.1.1",
"info": {"title": "Illustrative Items API", "version": "0.1.0"},
"paths": {
"/items": {
"get": {
"description": "Draft: authentication and error responses remain unspecified.",
"responses": {
"200": {
"description": "Items",
"content": {"application/json": {"schema": {
"type": "array",
"items": {"type": "object", "required": ["id", "name"], "properties": {
"id": {"type": "string"}, "name": {"type": "string"}
}}
}}}
}
}
}
}
}
}Chargez ces données dans le prompt, puis copiez-le dans WebAct pour essayer la tâche. Votre résultat peut différer de l'illustration.
Décisions et dépannage.
Une ébauche OpenAPI doit-elle inventer l’authentification d’un endpoint non documenté ?
Notez la lacune et demandez l’exigence réelle. Un schéma de sécurité généré ne doit pas être confondu avec une protection implémentée.
Pourquoi les clients générés échouent-ils malgré une spécification valide ?
Comparez schémas et comportement des statuts à l’API réelle. La validité structurelle ne prouve pas que le contrat documenté correspond à l’implémentation.
Référence pour ce processus.
Essayez avec votre propre source.
Remplacez l'exemple par vos données dans le prompt. Gardez les exigences nécessaires, puis copiez la tâche dans WebAct.
Personnaliser et copier la tâche ↑