Interface Completeness

Documentação insuficiente é um dos problemas mais frequentes que os consumidores de APIs enfrentam. É comum, por exemplo, que recursos não tenham descrições nos mostrando a que se destinam ou que uma requisição a um recurso falhe sem que o retorno de erro mostre o que deveríamos fazer para completar a chamada. Esses problemas podem ser evitados se houver uma governança estipulando que APIs só sejam implantadas em ambiente produtivo se sua documentação estiver satisfatória.

É exatamente para ajudar a visualizar o quão completa a documentação de uma API está que criamos a funcionalidade Interface Completeness.

Não existe uma tela específica para Interface Completeness; ela aparece no canto superior direito da tela de Overview de uma API:

completeness

A ferramenta analisa o Swagger da API e compara a quantidade de campos cadastrados com a quantidade total de campos que podem ser incluídos em um Swagger. Com base nessa comparação, é gerada uma porcentagem, que busca representar o quão completo o Swagger está. Além disso, com base nos problemas detectados, a funcionalidade oferece sugestões de melhoria que você pode implementar no Swagger (veja mais sobre isso abaixo).

Com isso, você consegue:

  • utilizar a porcentagem de completude do Swagger como requisito para promover uma API a um estágio específico de workflow (veja mais sobre isso abaixo);

  • assegurar que a API que você expõe ao público por meio do Portal de Desenvolvedores tem documentação suficiente (você escolhe expor uma API no Portal na tela de Overview de uma API).

Como posso interpretar a porcentagem do Interface Completeness?

Para chegar à porcentagem final, comparamos a quantidade de campos que estão cadastradas no Swagger da sua API com a quantidade total de campos que poderiam ser cadastrados. Utilizando nossa expertise em APIs, atribuímos pesos diferentes aos campos, para valorizar itens mais importantes (por exemplo, incluir o código HTTP de resposta vale mais do que incluir a descrição do erro). Também incluímos uma validação de formato para alguns campos, por exemplo:

  • descrições devem ter um mínimo de caracteres e não podem ser sequências como ABC ou 123;

  • o base path da API deve incluir o nome da API e a versão, e validamos se ambos são iguais ao nome e versão cadastrados.

De qualquer forma, o resultado final é quantitativo, não qualitativo: ele dá uma medida do grau de completude da documentação da API, mas não da qualidade do seu desenho. Por exemplo, checamos se a sua API tem uma descrição, não se a descrição é condizente com o que a API oferece e se está clara para o usuário. Você pode e deve utilizá-lo como uma etapa de checagem antes da exposição da API, para assegurar que existe um Swagger suficientemente completo para aquela API, mas não como validação da qualidade dela.

Quanto ao número que pode servir como um valor limiar de completude, isso depende da sua estratégia de APIs e do objetivo de cada API que você desenha. Por isso, você pode definir o valor que desejar para o requisito de Interface Completeness para que uma API possa ser promovida para um determinado estágio de workflow (veja mais sobre isso abaixo).

Pela nossa experiência com APIs e documentação de APIS, sugerimos que nenhuma API seja exposta ao público se não atingir um mínimo de 70% de Interface Completeness. Mais do que isso, indicamos que 85% de completude é uma porcentagem que representa um nível bastante satisfatório de documentação, então é melhor ainda usá-lo como valor mínimo. Mas isso é apenas uma sugestão; como tudo em uma governança APIs adaptativa, fique à vontade para estabelecer o limiar que funciona para o seu contexto.

Sugestões de melhoria ao Swagger

A funcionalidade também gera sugestões de melhoria a partir da checagem dos campos do Swagger da API. Para vê-las, clique em Suggestions, abaixo da porcentagem.

Você pode fazer as alterações utilizando o editor de Swagger (veja informações sobre ele aqui).

Após realizar as modificações e salvar a API como uma nova Revision, a avaliação de completude é feita novamente.

Exemplo de uso

Criamos uma API com uma descrição e base path, mas não incluímos nenhum recurso, o que gerou uma porcentagem baixa de completude:

completeness ex1

Então, incluímos esses dois recursos à nossa API:
completeness ex2 resources

Utilizando o editor de Swagger do Manager, incluímos os tipos de retorno de cada recurso, mensagens de erro com os códigos HTTP de resposta para cada recurso e incluímos descrições para algumas model properties. Isso tornou nossa API pronta para exposição:

completeness ex2

Campos checados

Estes são os campos que a funcionalidade checa para avaliar a completude da documentação da API (lembrando que há pesos diferentes para cada um):

API Recurso/Operación Modelo
  • Título

  • Descrição

  • Versão

  • Base path

  • Existência de recurso

  • Resumo de operação

  • Descrição de operação

  • Nome de parâmetro

  • Descrição de parâmetro

  • Código de resposta de operação

  • Descrição de resposta de operação

  • Nome de header de resposta de operação

  • Descrição de header de resposta de operação

  • Nome

  • Descrição

  • Nome de propriedade

  • Descrição de propriedade

Como usar Interface Completeness com Workflows

A funcionalidade de Workflows estabelece um controle dos estágios que marcam etapas de desenvolvimento das APIs. Lá, é possível customizar os requerimentos para que uma API seja promovida entre os estágios, o que permite ter visibilidade e controle do processo de desenvolvimento de cada API.

Um dos requisitos que podem ser usados para definir as regras de um estágio é uma porcentagem mínima de Interface Completeness. Nesse caso, se você definir que somente APIs com pelo menos 85% de grau de maturidade devem estar no estágio "Production" e incluir também o requerimento que somente APIs nesse estágio podem ser implantadas em ambiente de produção, então você conseguirá estabelecer que nenhuma API seja enviada para ambiente produtivo se não estiver com uma documentação satisfatória!

Você pode ler mais sobre Workflows aqui.

Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]