O Postman é uma ótima ferramenta para desenvolver e testar APIs RESTful criadas por outras pessoas ou testar e desenvolver as que você mesmo criou. Ele oferece uma interface de usuário elegante com a qual é possível fazer solicitações JSON, XML e até HTML, sem a necessidade de escrever um monte de código apenas para testar a funcionalidade de uma API.

O Swagger é um conjunto de ferramentas de código aberto criadas em torno da Especificação OpenAPI que podem ajudá-lo a projetar, criar, documentar e consumir APIs REST. As principais ferramentas do Swagger incluem:

  • Swagger Editor – editor no navegador onde você pode escrever as especificações OpenAPI.
  • Swagger UI – renderiza as especificações do OpenAPI como documentação interativa da API no navegador.
  • Swagger Codegen – gera stubs de servidor e bibliotecas de clientes a partir de uma especificação OpenAPI.

A especificação OpenAPI é um formato de descrição de API para APIs REST. Um arquivo OpenAPI permite que você descreva toda a sua API, incluindo:

  • Endpoints disponíveis (/ usuários) e operações em cada endpoint (GET / usuários, POST / usuários)
  • Parâmetros de operação Entrada e saída para cada operação
  • Métodos de autenticação da API REST
  • Informações de contato, licença, termos de uso e outras informações.

Bom, agora que entendemos o que cada ferramenta/serviço é e faz conseguimos entender onde aplicar cada uma. O OpenAPI vem se tornando um padrão da comunidade para compartilhar documentações de APIs RESTful, porém eu gosto muito da ferramenta do Postman para desenvolver e testar as APIs no dia a dia, porém as funcionalidades para times e compartilhamento da documentação do Postman são pagas, o que torna inviável o uso em pequenos projetos ou empresas com orçamento restrito, mas ao mesmo tempo manter duas bases de documentações é muito trabalhoso e pode chegar a ser inviável dependendo da quantidade de endpoints.

A solução!

A solução que eu encontrei foi centralizar e desenvolver todas as documentações das APIs no formato OpenAPI, porque como essa especificação é desenvolvida em um arquivo YAML ou JSON, conseguimos versionar esses arquivos por projetos, no caso de uma arquitetura em microserviços isso é extremamente úteis, e como o Postman permite a importação da especificação do OpenAPI, fica fácil de atualizar sua versão local.

Bom, se você como eu começou a desenvolver toda a sua documentação no Postman e agora está buscando em uma solução fácil e rápida para converter de Postman para OpenAPI, fique tranquilo, pois podemos usar o serviço gratuito da APIMatic para fazer essa conversão. Faça o registro no site e em poucos minutos tenha toda a sua documentação convertida!

2.7 10 votos
Nota do Artigo
Subscribe
Notify of
guest

1 Comentário
newest
oldest most voted
Inline Feedbacks
View all comments
Silvair Leite Soares
Silvair Leite Soares
2 anos atrás

Muito obrigado por compartilhar, estava a dias tentando converter a documentação da API Cielo eCommerce, eles só disponibilizam o arquivo do Postman na versão 1.0, a qual não é mais aceita pela versão atual do Postman.Com a utilização da “APIMatic” consegui importar e converter em Open API3.0.
Mais uma vez, muitíssimo obrigado.

1
0
Would love your thoughts, please comment.x