Cómo documentar un contrato API real con OpenAPI.
Una especificación API debe reflejar el contrato real, incluidos errores y autenticación. Marca lo desconocido en lugar de inventar una descripción pulida del endpoint.
Adapta el flujo de trabajo a tu tarea.
Documenta el endpoint, los parámetros, la autenticación y el contrato de respuesta reales con una versión OpenAPI especificada. Incluye los errores conocidos y señala lo desconocido en lugar de crear un contrato aparentemente completo basado en supuestos.
- Qué aportas
- Descripciones verificadas de endpoints y respuestas de ejemplo.
- Qué obtienes
- Borrador OpenAPI con contratos sin resolver señalados.
Mira la entrada y el resultado.
Entrada y salida ilustrativas · ejemplo didáctico, no una ejecución de WebAct en directo
Ejemplo campo
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.
Ejemplo completo
{
"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"}
}}
}}}
}
}
}
}
}
}Carga esta entrada en el prompt y cópialo en WebAct para probar la tarea. Tu resultado puede diferir del ejemplo.
Decisiones y solución de problemas.
¿Debe un borrador OpenAPI inventar la autenticación de un endpoint sin documentar?
Registra la laguna y pide el requisito real. Un esquema de seguridad generado no debe confundirse con protección implementada.
¿Por qué fallan los clientes generados aunque el documento de especificación sea válido?
Compara los esquemas y el comportamiento de los estados con la API real. La validez estructural no demuestra que el contrato documentado coincida con la implementación.
Referencia para este flujo de trabajo.
Pruébalo con tu propia fuente.
Sustituye el ejemplo por tu material en el prompt. Conserva los requisitos que necesites y copia la tarea en WebAct.
Personalizar y copiar la tarea ↑