Detector de Mudanças Quebradoras na API

Você está cruzando o contrato real de uma Web API em C# (controladores, DTOs, definições de rota) com seus consumidores em TypeScript/JavaScript para encontrar desvios de contrato — em ambas as direções — antes que cheguem à produção.

Quando usar isto

Acione quando o usuário pedir para:

• Verificar se uma mudança em DTO/controlador quebrará aplicações frontend ou cliente
• Verificar se o contrato da API do cliente e do backend ainda está sincronizado
• Auditar um endpoint específico, ou toda a superfície da API, em busca de mudanças quebradoras antes de um lançamento

Não use isto para:

• Gerar novo código de API a partir de uma especificação OpenAPI (veja openapi-to-application-code)
• Criar novos endpoints com documentação OpenAPI (veja aspnet-minimal-api-openapi)
• Comparar dois arquivos de especificação OpenAPI diretamente — esta habilidade lê código fonte, não especificações exportadas

Processo

1. Descobrir Políticas Globais de JSON e Nomenclatura:

   • Verifique Program.cs ou Startup.cs para opções de JSON ativas (por exemplo, JsonNamingPolicy.CamelCase, PropertyNamingPolicy, ou Newtonsoft CamelCasePropertyNamesContractResolver).
   • Use como padrão camelCase para mapeamento de campos em TypeScript/JavaScript se o camelCase global estiver configurado, a menos que seja substituído por um atributo explícito [JsonPropertyName("...")] na propriedade C#.
   • Ignore propriedades C# anotadas com [JsonIgnore].

2. Identificar a superfície do contrato C#. Para cada ação de Controlador no escopo:

   • Rota: [Route("...")] base + [HttpGet("...")] / [HttpPost("...")] da ação. Normalize parâmetros de rota (por exemplo, {id:int} ou {id:guid} $\rightarrow$ {id}).
   • DTO de Requisição: Extraia nomes de propriedades, tipos e regras de requisito:
     • Obrigatório se: anotado com [Required], [BindRequired], tiver o modificador required do C# 11 (public required string X), ou for um tipo de valor não anulável (int, Guid, bool) sem um valor padrão.
     • Opcional se: anulável (string?, int?), ou tiver um inicializador padrão.
   • DTO de Resposta: Nomes de propriedades, tipos e nulidade.
   • Códigos de Status Explícitos: atributos [ProducesResponseType(statusCode)] e caminhos de retorno explícitos de StatusCode(...).

3. Encontrar o consumidor TypeScript/JavaScript correspondente (com Correspondência Normalizada de URL):

   • Correspondência de cliente auto-gerado (alta confiança): procure por arquivos de cliente gerados (saída NSwag/OpenAPI Generator) e combine diretamente pelo nome do método/interface gerado.
   • Correspondência de serviço/cliente escrito à mão (confiança média):
     • Procure em arquivos TypeScript/JavaScript por chamadas de cliente HTTP (fetch, axios, Angular HttpClient, ky, etc.) cujo padrão de URL normalizado corresponda à rota do controlador.
     • Normalize strings de template e concatenações (por exemplo, ${this.apiUrl}/users/${id} ou baseUrl + '/users/' + userId $\rightarrow$ /users/{id}).
     • Combine rotas normalizadas com rotas C# independentemente da nomenclatura de variáveis em TypeScript/JS.
   • Nenhuma correspondência encontrada: relate como "consumidor de cliente não localizado" em vez de adivinhar — não presuma que um endpoint não está sendo usado apenas porque uma correspondência não foi encontrada estaticamente.
   • Rotule cada descoberta com qual desses três métodos foi usado para localizá-la.

4. Comparar backend → frontend/cliente (quebra o cliente):

   • Uma propriedade de DTO renomeada ou removida que a interface ou modelo de objeto TypeScript/JS ainda espera
   • Um novo campo de requisição obrigatório que o cliente nunca envia
   • Um código de status de resposta que o cliente não lida (por exemplo, o controlador agora retorna 409 Conflict, mas o manipulador de erros do cliente lida apenas com 400/500)
   • O tipo de um campo de resposta mudou (por exemplo, long $\rightarrow$ string, ou não anulável $\rightarrow$ anulável) de uma forma que o tipo do cliente assume de maneira diferente

5. Comparar frontend/cliente → backend (código cliente obsoleto/morto vs. bugs silenciosos):

   • Campo morto inofensivo: O cliente envia uma propriedade de payload que o backend ignora sem erro.
   • Bug silenciosamente quebrado (Alta Severidade): A lógica do cliente lê uma propriedade de resposta que o backend não retorna mais (resultando em undefined em tempo de execução e potenciais falhas na aplicação).

6. Produzir o relatório (veja Formato de Saída). Esta habilidade não modifica o código.

Formato de Saída

1. Escopo Auditado — Controladores, DTOs e arquivos TypeScript/JavaScript auditados, juntamente com as políticas de nomenclatura JSON detectadas (por exemplo, camelCase habilitado via Program.cs).

…