Thanks for your feedback!
EDIT
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:
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:
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).
|
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:
Então, incluímos esses dois recursos à nossa API:
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:
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 |
|---|---|---|
|
|
|
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.
Share your suggestions with us!
Click here and then [+ Submit idea]