Primeiro o contrato
O contrato de API implementado por cada serviço é a fonte de verdade para sua documentação de referência. Documente a API usando a versão de OpenAPI ou Swagger implementada pelo serviço. Não descreva uma API como OpenAPI 3.1 a menos que esse serviço a tenha adotado.
Comportamento específico do serviço
Não presuma padrões compartilhados entre as APIs da Lerian. Para cada operação, documente o comportamento implementado por aquele serviço, incluindo:
- Requisitos e cabeçalhos de autenticação.
- Nomes de parâmetros e campos JSON.
- Códigos de status de resposta e formatos de data.
- Media type de PATCH e semântica de propriedades omitidas ou
null. - Comportamento de DELETE e suporte a metadados.
Erros
Envelopes de erro e formatos de códigos de erro variam conforme o produto. Use o schema de resposta e a referência de erros do serviço específico antes de tratar um erro programaticamente. Não publique um corpo, prefixo, intervalo numérico ou conjunto de campos globais a menos que sejam implementados em todos os serviços cobertos.
Páginas de referência
Renderize páginas de operações da API a partir da especificação correspondente, em vez de duplicar manualmente a prosa de requisição, resposta ou erro. Veja o modelo de referência da API para o formato de stub da operação.
Antes de publicar
- Verifique o método, o caminho, os schemas e os media types com o contrato do serviço.
- Preserve o mesmo método e caminho em cada idioma renderizado.
- Atualize o contrato canônico do serviço antes de sincronizar as especificações de API renderizadas.