Primero el contrato
El contrato de API implementado por cada servicio es la fuente de verdad para su documentación de referencia. Documenta la API usando la versión de OpenAPI o Swagger que implemente el servicio. No describas una API como OpenAPI 3.1 a menos que ese servicio lo haya adoptado.
Comportamiento específico del servicio
No supongas valores predeterminados compartidos entre las APIs de Lerian. Para cada operación, documenta el comportamiento implementado por ese servicio, incluidos:
- Requisitos y encabezados de autenticación.
- Nombres de parámetros y campos JSON.
- Códigos de estado de respuesta y formatos de fecha.
- Media type de PATCH y semántica de propiedades omitidas o
null. - Comportamiento de DELETE y soporte de metadatos.
Errores
Los envelopes de error y los formatos de códigos de error varían según el producto. Usa el esquema de respuesta y la referencia de errores del servicio específico antes de manejar un error programáticamente. No publiques un cuerpo, prefijo, rango numérico o conjunto de campos globales a menos que estén implementados en todos los servicios cubiertos.
Páginas de referencia
Renderiza las páginas de operaciones de API a partir de la especificación correspondiente en lugar de duplicar manualmente la prosa de solicitud, respuesta o error. Consulta la plantilla de referencia de API para el formato de stub de operación.
Antes de publicar
- Verifica el método, la ruta, los esquemas y los media types con el contrato del servicio.
- Conserva el mismo método y ruta en cada idioma renderizado.
- Actualiza el contrato canónico del servicio antes de sincronizar las especificaciones de API renderizadas.