Validando especificações de API em Insights de APIs

Você pode acessar as regras de validação de especificação de API para verificar se as especificações de API estão completas, consistentes e seguem as práticas recomendadas.

As regras de validação identificam problemas estruturais no início da importação ou análise, melhorando a qualidade geral da API. Você pode gerenciar essas regras para impor a padronização nas especificações de API e reduzir erros verificando se há campos ausentes ou incorretos antes que as APIs sejam publicadas ou usadas na produção.

Armazenando especificações de API

A tabela Especificação de API [sn_api_insights_ws_api_specification] armazena os documentos de especificação que descrevem APIs individuais. Cada registro inclui os seguintes detalhes para identificar a API à qual a especificação pertence e para gerenciar várias versões.

Tabela 1. Detalhes da especificação da API

Campo	Descrição
Nome	Nome da API.
Versão	Versão da API.
Tipo	Formato e versão do padrão de especificação da API que está sendo usado. Por exemplo, openapi3.0.0 Para uma especificação OpenAPI.
Estado	Status atual que indica se a especificação da API foi validada em relação às regras aplicáveis e ao resultado da validação. Os valores válidos são: Não processado : Indica que a especificação da API não foi validada. Válido : Indica que a especificação da API foi validada e processada com sucesso ou com avisos. Se avisos estiverem presentes, os detalhes serão exibidos em Mensagem campo. Inválido Indica que a especificação da API foi validada, mas contém erros. Os detalhes do erro são exibidos em Mensagem campo.
Especificações	Conteúdo completo do arquivo de especificação da API. Nota: Para OpenAPI, inclui o documento OpenAPI completo que descreve endpoints, métodos e esquema.
Mensagem	As mensagens são geradas após o processamento de todas as regras de validação para o tipo de especificação. Eles incluem erros ou avisos com explicações.

Estrutura da regra de validação

A tabela Regra de validação de especificação [sn_api_insights_ws_spec_validation_rule] armazena regras de validação para as especificações de API definidas na tabela Especificação de API [sn_api_insights_ws_api_specification].

Nota:

A função sn_cmdb_editor é necessária para editar ou excluir regras de validação e a função cmdb_read para exibi-las.

Cada regra de validação contém os seguintes componentes-chave:

Tabela 2. Componentes da regra de validação

Componente	Descrição
Especificações	Especificação de API para a qual a regra foi projetada.
Versão	Versão da especificação da API que a regra valida. Se especificada, a regra se aplicará somente a essas versões. Para restringir a validação a versões específicas, especifique-as em Versão campo. Separe vários valores com vírgulas. Por exemplo, 1,0,1,1,2,0 . Nota: . Versão Deixado em branco, a regra é executada para todas as versões instaladas do tipo de especificação de API especificado.
Tipo	Tipo de validação a ser executada. Os valores válidos são: Caminho : Verifica se as chaves específicas estão presentes em matrizes de objetos, objetos individuais ou ambos, nas seções designadas do documento de especificação da API. Valor esperado : Valida se a chave especificada corresponde aos valores esperados especificados em Valor campo. Esta validação se aplica somente a uma única chave especificada em Chave campo.
Chave	Parte da especificação a ser verificada. Se nenhum valor esperado for fornecido, você poderá inserir várias chaves no Chave separado por vírgulas.
Valor	Valores esperados para a chave especificada em Chave campo. Separe vários valores com vírgulas.
Gravidade	Nível de gravidade do resultado da regra de validação, um aviso ou um erro. Nota: Quando definida como aviso, a especificação da API permanecerá válida se a regra não for atendida, indicando que não é uma falha e somente uma mensagem será exibida.
Mensagem	Explicação do problema quando a regra é acionada.
Ativo	Opção para ativar a regra. Somente regras ativas são acionadas pelo API Specification Validationtrabalho agendado.

Processo de validação de especificação de API

. API Specification ValidationO trabalho agendado valida automaticamente as especificações de API não processadas em relação às regras ativas com base no tipo de especificação para garantir a conformidade com os padrões necessários.

O processo de validação inclui:

1. Recuperando todas as regras de validação ativas da tabela Regra de validação de especificação [sn_api_insights_ws_spec_validation_rule].
2. Selecionar APIs marcadas como não processadas na tabela Especificação de API [sn_api_insights_ws_api_specification].
3. Aplicar regras de validação relevantes a cada API selecionada com base em seu tipo de especificação, como OpenAPI.
4. Verificando a presença ou a exatidão de campos específicos ou seus valores na especificação da API.
5. Atualizando o status de processamento e capturando erros ou avisos.

Regras predefinidas para especificações do OpenAPI

Por padrão, a aplicação inclui as seguintes regras de validação para especificações do OpenAPI:

Validar marcadores

Verifica se cada marcador na especificação da API inclui um nome campo. . nome o campo está ausente, o sistema retorna uma mensagem de aviso, mas marca a especificação como válida.

Validar seções necessárias

Verifica se a especificação da API inclui as seções de nível superior necessárias: informações , caminhos e componentes . Se alguma dessas seções estiver ausente, o sistema retornará uma mensagem de erro e marcará a especificação como inválida.

Validar seção de servidores

Verifica se a especificação da API inclui um servidores seção que define os endpoints do servidor. . servidores a seção está ausente, o sistema retorna uma mensagem de erro e marca a especificação como inválida.

Essas regras predefinidas verificam seções críticas, como marcação, metadados e definições de servidor nas especificações da OpenAPI.