Como documentar um contrato API real com OpenAPI.
Uma especificação API deve refletir o contrato real, incluindo erros e autenticação. Marque comportamentos desconhecidos em vez de inventar uma descrição refinada do endpoint.
Adapte o fluxo à sua tarefa.
Documente endpoint, parâmetros, autenticação e contrato de resposta reais usando uma versão OpenAPI especificada. Inclua erros conhecidos e marque o desconhecido em vez de criar um contrato aparentemente completo a partir de hipóteses.
- O que você fornece
- Descrições verificadas dos endpoints e respostas de exemplo.
- O que você recebe
- Rascunho OpenAPI com contratos pendentes sinalizados.
Veja a entrada e o resultado.
Entrada e saída ilustrativas · exemplo didático, não uma execução real do WebAct
Exemplo 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.
Exemplo 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"}
}}
}}}
}
}
}
}
}
}Carregue esta entrada no prompt e copie para o WebAct para testar a tarefa. Seu resultado pode ser diferente da ilustração.
Decisões e solução de problemas.
Um rascunho OpenAPI deve inventar autenticação para um endpoint não documentado?
Registre a lacuna e solicite o requisito real. Um esquema de segurança gerado não pode ser confundido com proteção implementada.
Por que clientes gerados falham apesar de uma especificação válida?
Compare esquemas e comportamento dos status com a API real. Validade estrutural não estabelece que o contrato documentado corresponde à implementação.
Referência para este fluxo de trabalho.
Teste com sua própria fonte.
Substitua o exemplo pelo seu material no prompt. Mantenha os requisitos necessários e copie a tarefa para o WebAct.
Personalizar e copiar a tarefa ↑