Compartilhar:
){kind=small}
Lorna é engenheira de software e tem um vício incurável por escrever em blogs. Ela tenta domar as palavras e o código na mesma medida.
A OpenAPI facilita as integrações
Tempo de leitura: 3 minutos
Levamos a sério nossa documentação para desenvolvedores muito a sério, especialmente nossa Referência da API. Os documentos de referência são gerados a partir de uma descrição legível por máquina de cada API, em formato OpenAPI . Trabalhar com um formato baseado em texto e legível por máquina facilita a manutenção dos documentos. Isso é ótimo para nós, que cuidamos da documentação, mas como isso ajuda você, o usuário? Que bom que você perguntou!
Dê uma olhada em qualquer uma das nossas páginas de referência de API. Lá você encontrará um botão chamado “Baixar a especificação OpenAPI 3” e, ao clicar nele, receberá o arquivo YAML. Você também pode encontrar todas as nossas especificações na definitions/ pasta do nosso repositório GitHub de Especificações de API.
Usar um formato padrão de descrição de API, como o OpenAPI, dá acesso a uma grande variedade de ferramentas que interpretam esses arquivos. Vou mostrar a vocês algumas das minhas coisas favoritas para fazer com uma especificação OpenAPI!
Quando você está experimentando uma API desconhecida, pode ser frustrante ter que vasculhar a documentação para entender como montar uma solicitação específica. O Postman oferece suporte à importação de arquivos de especificação OpenAPI e os transforma em uma coleção pronta de solicitações de API. Essa é uma maneira excelente de testar uma nova API sem precisar gastar muito tempo lendo documentação e copiando nomes de campos para o meu cliente HTTP.
Sou um grande fã dessa abordagem e a utilizo com muita frequência, mesmo em APIs que conheço tão bem que poderia digitar os comandos do curl de olhos fechados. É uma maneira muito rápida de interagir corretamente com uma API e acho isso muito útil.
Quando viajo, às vezes fico sem uma conexão confiável à internet. Se eu tiver o arquivo de especificação da OpenAPI salvo no meu computador (spoiler: eu sempre tenho os arquivos de especificação salvos no meu computador, pois trabalho bastante neste repositório!), posso usar uma das ferramentas de documentação da OpenAPI para criar documentos que posso usar no meu laptop.
Uma opção é usar a ferramenta que nós mesmos utilizamos, que é Nexmo OAS Renderer. É uma ferramenta de código aberto baseada em Ruby que nós mesmos criamos e publicamos. No entanto, ela não está vinculada às nossas especificações; eu a utilizo principalmente para nossas próprias APIs, mas ela deve funcionar com qualquer arquivo de especificação OpenAPI v3 válido.
A outra abordagem que às vezes utilizo é uma ferramenta de código aberto, desta vez em NodeJS, chamada ReDoc. Mais uma vez, ela é útil para criar documentação em HTML a partir de uma especificação OpenAPI. Experimente as duas opções e escolha a sua favorita!
A descrição da API contém informações sobre todos os aspectos de uma API. São tantas informações, na verdade, que seria possível fazer uma imitação muito boa dessa API com todos os detalhes incluídos.
Uma excelente representação da API a partir de uma especificação OpenAPI é exatamente o que o Prism, da Stoplight, oferece. É uma ferramenta NodeJS; instale-a com npm e, em seguida, inicie-a localmente, e você terá sua própria cópia privada da API a partir de um arquivo de especificação OpenAPI!
Eu uso isso principalmente durante o desenvolvimento, quando posso precisar chamar o mesmo endpoint da API várias vezes para ter certeza de que estou lidando corretamente com as diversas respostas. Um servidor simulado é mais rápido do que uma API remota e muito mais econômico. Também não há limites de taxa. Para quem está integrando uma API, ferramentas como servidores simulados são um grande auxílio. Para nós, como provedores de API, não precisamos criar nem oferecer suporte a um ambiente de teste para que as pessoas possam desenvolver suas integrações em um espaço seguro; isso é um benefício adicional de usar o OpenAPI.
Escolhi três aspectos que, na minha opinião, fazem uma grande diferença para os usuários de API quando o provedor disponibiliza as especificações OpenAPI. A Vonage não se destaca particularmente na publicação de descrições de API; eu esperaria que a maioria dos provedores modernos de API fizesse o mesmo. Espero que você tenha algumas ideias sobre o que gostaria de tentar para melhorar sua próxima integração de API. Conte para a gente se você já está usando uma dessas abordagens ou qual delas gostaria de experimentar em seguida.
Quer saber mais sobre o OpenAPI e nossas ferramentas? Aqui estão algumas leituras adicionais para você:
A Iniciativa OpenAPI: https://www.openapis.org
O melhor lugar para procurar ferramentas para usar com o OpenAPI: https://openapi.tools
O Postman para importar uma especificação e criar uma coleção de solicitações a ser utilizada: https://postman.com
Prism, o servidor simulado: https://stoplight.io/open-source/prism
Mais documentos específicos da Vonage sobre a OpenAPI, incluindo informações mais detalhadas sobre como usar o Postman e o Prism, e sobre como gerar documentação: /getting-started/Concepts/openapi