A MoreLogin publica uma versão de snapshot do contrato legível por máquina no info.version de cada documento OpenAPI. A versão usa o formato de calendário YYYY-MM-DD e identifica o contrato de documentação, não um segmento de versão na URL da requisição.
| Mudança | Classificação | Tratamento na documentação |
|---|---|---|
| Adicionar um campo de requisição ou resposta opcional, uma operação ou um valor de enumeração | Aditiva | Registrar no changelog e atualizar todas as especificações localizadas |
| Esclarecer descrições ou corrigir um exemplo sem mudar o comportamento em execução | Correção de documentação | Registrar quando altera a orientação de integração |
| Tornar um campo opcional obrigatório, remover/renomear um campo ou operação, restringir valores aceitos ou mudar a semântica estabelecida | Quebra | Fornecer um caminho de migração e um contrato versionado separadamente antes da remoção |
Marcar uma operação com deprecated: true | Descontinuação | Documentar o substituto, a data do anúncio e a data prevista de remoção quando aprovada |
Os clientes devem ignorar campos de resposta e valores de enumeração desconhecidos quando sua lógica de negócio permitir. Isso reduz quebras causadas por versões aditivas.
A operação OpenAPI é o local legível por máquina com autoridade. Uma operação descontinuada precisa incluir:
deprecated: true- uma descrição que nomeie o substituto ou afirme que não existe
- uma entrada de anúncio no changelog da API
- uma data prevista de remoção somente depois que os responsáveis pelo produto e pelo gateway a aprovarem
Nenhum período mínimo universal de descontinuação é garantido atualmente. Até que uma data de remoção seja explicitamente publicada, os clientes devem tratar a operação como suportada, mas planejar a migração.
O comportamento em execução continua sendo a autoridade. OpenAPI, exemplos, cópias localizadas, o manifesto de comportamento das operações e o changelog são verificados juntos na CI para evitar desvio de contrato.
A aprovação no controle de qualidade do repositório comprova que os arquivos OpenAPI, exemplos, links, cópias localizadas e artefatos de governança são internamente consistentes.
A verificação das páginas renderizadas comprova que rotas representativas da documentação carregam e são exibidas sem erros no cliente.
Somente um teste de fumaça autenticado na API implantada pode comprovar que o comportamento de produção corresponde ao contrato publicado. Este repositório não executa esse teste por padrão; portanto, as notas de versão devem informar separadamente quando a verificação de produção foi realizada.