Как документировать реальный контракт API в OpenAPI.
Спецификация API должна отражать реальный контракт, включая ошибки и аутентификацию. Отмечайте неизвестное поведение вместо выдумывания красивого описания эндпоинта.
Адаптируйте процесс под свою задачу.
Документируйте реальный эндпоинт, параметры, аутентификацию и контракт ответа в указанной версии OpenAPI. Включайте известные ошибки и отмечайте неизвестное вместо создания внешне полного контракта на допущениях.
- Что вы предоставляете
- Проверенные описания эндпоинтов и примеры ответов.
- Что вы получите
- Черновик OpenAPI с отмеченными неуточнёнными контрактами.
Посмотрите входные данные и результат.
Иллюстративные входные и выходные данные · учебный пример, а не реальный запуск WebAct
Полей ввода: Пример
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.
Готовый пример
{
"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"}
}}
}}}
}
}
}
}
}
}Добавьте эти данные в промпт и скопируйте его в WebAct, чтобы попробовать задачу. Ваш результат может отличаться от примера.
Решения и устранение проблем.
Должен ли черновик OpenAPI выдумывать аутентификацию для недокументированного эндпоинта?
Отметьте пробел и запросите реальное требование. Созданную схему безопасности нельзя принимать за реализованную защиту.
Почему сгенерированные клиенты не работают при корректном документе спецификации?
Сравните схемы и поведение статусов с реальным API. Структурная корректность не подтверждает соответствие документированного контракта реализации.
Источник для этого сценария.
Попробуйте на собственном источнике.
Замените пример своим материалом в промпте. Сохраните нужные требования и скопируйте задачу в WebAct.
Настроить и скопировать задачу ↑