Recorrentemente, o desenvolvedor de software necessita retroceder vários commits a fim de voltar seu código para uma versão estável. Um exemplo disso é quando temos um fluxo de trabalho onde um repositório GIT tem suas branches associadas à ambientes de implantação através de pipelines DevOps, tal como o exemplo da Figura 1, a seguir:

Figura 1: Exemplo de GIT Flow com pipeline típico.

Para que uma versão “suba” para homologação, seria necessário que se fizesse um merge request da branch “feature-new-func” em “develop” e, por sua vez, de “develop” em “master”. Enquanto o ambiente de homologação está em uma dada versão, associada a um commit específico, é possível que a branch “develop” fique bem mais atualizada conforme as atividades de desenvolvimento ocorrem, conforme mostra a Figura 2:

Figura 2: Exemplo de diferenças de histórico entre as branches citadas no exemplo anterior.

Como fazer então para que, caso necessitemos ter em “develop” a versão estável do commit A novamente, possamos reverter sem quebrar o fluxo e perder o histórico?

Encontrei a solução recentemente, ao passar por esse problema no meu trabalho, no Stack Overflow, onde o autor da resposta dá os créditos da abordagem a Jeff Ferland e Charles Bailey. Ela pode ser resumida assim:

$ git reset --hard A # A é o commit alvo
$ git reset --soft D # D é o commit mais recente
$ git commit -am "Rollback to commit A"

Basicamente, o git reset –hard destrói todas as mudanças que aconteceram após o commit A, voltando para ele. Em seguida, o git reset –soft “voltará” para o commit D, o mais atual, mais as mudanças necessárias para que se chegasse ao commit A. O resultado será um novo commit idêntico ao commit que se quer reverter, preservando-se o histórico. Observe que se você por o código do alvo na mensagem do novo commit, o ambiente de GIT poderá criar um link para que você possa saber a que commit ele reverteu para.

Se chamarmos o código do commit resultante de A’ e utilizarmos o seguinte comando:

$ git diff A A'

Verificaremos que não obtivemos saída, ou seja, apesar de commits diferentes, eles são idênticos.

Espero que a dica de hoje seja útil nos reverts do dia a dia.

Figura 1: Visão geral da arquitetura de exemplo.

Aprimeira coisa que muitos fariam seria modificar o service do mongodb para atribuir-lhe um IP público e, então, realizar o acesso. No entanto, esta manobra exporia o banco de dados a riscos de segurança e, se não houver um método seguro de autenticação, podemos ter dados roubados ou sequestrados por ataques ransomware. Mas para quê expor o serviço a riscos desnecessários se temos uma alternativa mais segura e cômoda para isso? Esta alternativa é o port forwarding.

Port forwarding

O port forwarding permite redirecionar uma porta local (localhost) para uma porta remota na aplicação através de um túnel seguro. Veja a seguir como poderíamos fazer o redirecionamento de portas da nosso pod do mongo-db:

kubectl port-forward mongodb-wr6mkb 28015:27017

A porta de entrada remota é a 27017. A 28015, por sua vez, é a porta do localhost que foi mapeada para a porta remota. Assim poderíamos nos conectar normalmente ao banco através do endereço localhost:27017. Assim que o processo de port fowarding fosse finalizado, a conexão estaria encerrada.

Também é possível realizar um port foward através do service e do deployment ou outros tipos de recursos, isto é, não apenas do pod. A seguir, uma amostra de como faríamos a mesma conexão acima mas através destes recursos:

# via deployment
kubectl port-forward deployment/mongodb 28015:27017

# via service
kubectl port-forward service/mongodb 28015:27017

Tenha em mente que realizando o port forwarding desta maneira o load balancer redirecionaria a conexão para uma instância aleatória em caso de réplicas, o que não é o caso aqui, pois o deployment tem somente um pod.

Quer saber mais?

O que foi explanado neste artigo é um uso bem simples, fácil e que supre a maior parte das necessidades do dia a dia. O port forwarding é muito mais poderoso do que isso! Se você quer saber mais, as páginas a seguir serão de grande valia:

• Use Port Forwarding to Access Applications in a Cluster

• port-forward reference

• Clique aqui para acessar a lista de títulos gratuitos da Springer em Inglês e Alemão.

Bônus: Lista de Links de PDFs para Download

407 links diretos dos PDFs dos títulos disponibilizados pela Springer. Somente o livro Literature and Medicine não está presente, pois não disponibilizou link para seu PDF. Os títulos pesam por volta de 10GB.

https://link.springer.com/content/pdf/10.1007%2Fb100747.pdf
https://link.springer.com/content/pdf/10.1007%2Fb100507.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-21736-9.pdf
https://link.springer.com/content/pdf/10.1007%2Fb99417.pdf
https://link.springer.com/content/pdf/10.1007%2Fb97469.pdf
https://link.springer.com/content/pdf/10.1007%2F0-387-28117-7.pdf
https://link.springer.com/content/pdf/10.1007%2Fb104645.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-32353-4.pdf
https://link.springer.com/content/pdf/10.1007%2F0-387-36218-5.pdf
https://link.springer.com/content/pdf/10.1007%2F0-387-36274-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-36601-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-37575-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-40065-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-45524-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-46271-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-46312-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-49312-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-68566-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-72071-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-72579-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-74365-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-75959-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-76501-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-77650-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-78341-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-79054-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-84858-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-87573-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-88698-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-88963-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-93837-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4020-5719-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4020-6099-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4020-6808-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-35963-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-44874-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-03762-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-56194-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-0400-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-27877-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-44794-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4419-9479-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-18842-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-48936-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-21239-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-7091-0715-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4419-6488-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-01851-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-3058-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-26551-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-46321-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-13072-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-4556-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4615-1077-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-02099-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-37434-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-10-2045-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-57040-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-23042-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-53883-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-90-481-2516-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4899-7454-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-53785-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-51118-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-57589-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4419-1120-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-23026-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-44738-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-05699-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-47831-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-31791-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-54083-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4612-1844-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-84800-070-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-19864-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-61088-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-46162-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-33916-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-32862-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-30250-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-1194-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4613-0139-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-54064-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-7116-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-43341-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4419-0641-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4419-5653-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-12682-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4471-7307-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-53045-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-33143-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-31089-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-12742-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-52250-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4471-5134-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-28887-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4419-9504-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-45171-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-8349-6331-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-84882-935-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-07806-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-14142-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-37314-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-20951-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-50091-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-540-77974-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-19596-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-53022-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4471-4474-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-54413-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-37902-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-46394-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-6374-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4612-4374-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-59731-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-22309-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-30319-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-2212-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-49887-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-94-007-5757-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-14941-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-2122-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-58307-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-6271-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-21936-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-09351-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-21990-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-9170-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-55309-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4471-5201-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-2614-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-20451-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4612-4360-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-09171-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-94-007-1171-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-23012-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-4809-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4419-0925-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-658-07884-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-27265-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-57883-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-31650-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-01195-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-54349-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-43715-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-4560-67-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-23428-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-94-007-1211-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-27104-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-55444-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-63913-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-44561-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-34132-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-3954-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-29854-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-55615-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-46407-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4419-9982-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-53919-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-24551-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-10-1802-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4471-6419-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-6572-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-84800-322-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-6940-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4612-0979-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-11080-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-30304-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-29716-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-04101-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-24346-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4613-0041-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-2712-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-540-76504-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-7630-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-33405-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-31036-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-1151-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-40975-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-3618-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-10091-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-3523-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-62872-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-56475-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-5538-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-00401-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-03623-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-19464-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-20556-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-6227-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-54398-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-13809-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-94-017-8771-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-2113-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-22951-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-4-431-54526-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4419-6646-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-65867-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-7138-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-00894-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-44048-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-12493-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-9236-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-287-212-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-28980-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-29791-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-84628-642-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-20059-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-51412-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-20600-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-19425-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-54817-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-44127-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-6786-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-24331-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-50651-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-54486-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-3987-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-540-93804-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-8933-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-50319-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-39439-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-57750-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-05290-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-01769-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-94-007-6863-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-0867-7.pdf
https://link.springer.com/content/pdf/10.1007%2F1-84628-168-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4419-7288-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-540-69934-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-49810-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-14240-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-21173-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-658-10183-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-45776-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-1911-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-15195-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-7807-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4757-0576-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-29659-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-6486-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4471-6642-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4899-7550-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-540-32899-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-24280-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-3143-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-19587-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-2623-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-540-27752-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-50017-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-7946-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-61185-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-46950-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-18539-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-16874-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-25970-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-6849-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-34195-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-94-017-7242-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-15666-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-23880-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-49875-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-18398-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-94-007-6113-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-2766-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-2197-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-14777-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-9138-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4612-1272-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4471-5361-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4471-5601-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4471-6684-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-9126-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4757-2519-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-55606-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-57252-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-25675-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-8687-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-642-20144-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4614-4262-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-44899-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-0-387-71481-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-14454-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-48848-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-49849-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-58715-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-64786-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-65451-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-10-5218-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-6676-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-61158-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-66631-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-70920-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-70790-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-63133-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-49279-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-64410-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-66772-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-68588-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-68598-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-72547-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-58487-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-67395-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-65439-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-73004-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-66219-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-75771-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-73123-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-94-024-1144-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-56272-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-56509-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-68834-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-73132-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-65094-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-72682-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-59978-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-65682-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-77649-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-76442-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-78729-9.pdf
https://link.springer.com/content/pdf/10.1057%2F978-1-349-95348-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-68301-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-78361-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-77809-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-55381-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-77425-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-13-0399-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-91041-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-74965-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-57265-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-13-1090-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-78181-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-89491-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-91722-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-72911-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-91575-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-92207-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-95381-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-63588-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-91890-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-89292-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-72314-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-75502-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-75708-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-92804-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-94463-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-72347-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-92429-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-95762-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-92333-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-13-2475-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-56707-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-94313-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-98833-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-97298-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-02405-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-77434-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-91155-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-96622-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-96713-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-00581-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-10-8297-9.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-10-8321-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-13-0785-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-75804-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-99516-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-99118-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-02604-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-03255-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-94743-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-13-2023-1.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-00464-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-77315-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-00467-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-01279-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-04516-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-99420-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-71288-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-72000-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-05609-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-74373-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-96337-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-05900-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-13-6643-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-10552-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-98875-7.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-12489-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-13-3621-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-74746-0.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-13005-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-13605-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-00710-2.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-12727-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-13020-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-15671-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-11117-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-15224-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-18435-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-13788-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-319-68837-4.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-13-7496-8.pdf
https://link.springer.com/content/pdf/10.1007%2F978-981-13-8759-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-19182-5.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-20290-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-030-25943-3.pdf
https://link.springer.com/content/pdf/10.1007%2F978-1-4939-9621-6.pdf
https://link.springer.com/content/pdf/10.1007%2F978-3-662-56233-8.pdf

Atualização: Este artigo foi republicado aqui.

Diferenças entre bibliotecas, APIs e SDKs

Antes de tudo, precisamos estar cientes do conceito de uma biblioteca de programação, ainda que o mesmo pareça trivial. Ter isso em mente pode permitir que façamos algo mais direcionado a nosso objetivo e a decidir se o que temos o atinge ou não. Será que o que você quer ou precisa é de uma biblioteca? De um SDK inteiro, ou apenas uma API? Nesta seção, abordaremos a diferença entre estes três elementos de auxílio ao desenvolvimento e reuso de software. Baseei-me, em parte, no artigo “Framework vs Library vs Platform vs API vs SDK vs Toolkits vs IDE”, publicado na Medium, cujo conteúdo achei bem explicado e sucinto, além de ter outros conceitos que não abordaremos aqui, como toolkits e IDEs. No entanto, é importante ressaltar que utilizamos, muitas vezes, de maneira intercambiável estes conceitos.

Biblioteca

Conjunto de códigos com funcionalidades específicas e que são utilizadas recorrentemente, através da importação dos mesmos no seu próprio código. Podem vir disponíveis nativamente na linguagem de programação em uso (stdio.h e math.h do C/C++, por exemplo), sistemas operacionais (como o Linux Headers) ou por terceiros (como o OpenCV, para lidar com visão computacional). Permite que o desenvolvedor “terceirize” inúmeras tarefas e se preocupe com o negócio em si para o qual está programando. São disponibilizados, geralmente, através pacotes compilados ou não que são ligados ao programa em tempo de compilação ou execução.

Application Programming Interface (API)

Se refere a interface através do qual um ou mais recursos são disponibilizados para acesso ao programador, acesso este que pode ser feito através de bibliotecas. Pense na Google Maps API, por exemplo. Existem recursos computacionais na nuvem que lidam com problemas relacionados a geolocalização, cartografia e outros. Estas funcionalidades são disponibilizadas através de interfaces RESTful (através de URLs e verbos HTTP), por exemplo, sendo isto, então, um API. Por fim, o acesso a estas APIs podem ser feitos diretamente ou através do uso de bibliotecas, com códigos que encapsulam as consultas a esta interface.

Software Development Kit (SDK)

É um pacote completo e heterogêneo de desenvolvimento para alguma plataforma, que pode variar bastante e incluir bibliotecas, documentação, compiladores, ambientes de desenvolvimento integrado (IDEs), etc.

OpenAPI

Serviços RESTful se baseiam em disponibilizar recursos, que costumam ser entidades definidas no modelo de dados (passíveis de modificação de estado), através de endpoints URL (localizadores únicos) e verbos HTTP (que são relacionados a ações que se quer tomar em para modificar o estado do recurso).

Tomemos como exemplo um cadastro de livros em uma biblioteca. Após a modelagem de dados, encontramos a entidade Livro, com os atributos código, título, autor e número de páginas. Este recurso é disponibilizado em nosso serviço através do endpoint /livro. E há quatro ações de interesse: cadastrar, buscar/listar, editar e apagar um livro do sistema, que serão realizadas através dos verbos POST, GET, PUT e DELETE, respectivamente. Esta seria a visão geral do cenário:

# Cadastrar livro
POST /livro (código, título, autor, n_páginas)
# Buscar livro
GET /livro/{código}
# Listar livros
GET /livro
# Atualizar dados de um livro
PUT /livro/{código} (título, autor, n_páginas)
# Apagar livro do sistema
DELETE /livro/{código}

O que acabamos de fazer? Uma descrição da API. Um desenvolvedor pode utilizá-la para fazer consultas a API, seja diretamente ou através de programação, sem se preocupar com como a mesma é ou será implementada, desacoplando o trabalho, dividindo responsabilidades, facilitando testes e validações, além de servir como documentação do sistema. E que tal se existisse um padrão de descrição de APIs? Isso existe também, não somente um. Assim como serviços que seguem o padrão SOA podem ser descritos através do WSDL, os que seguem RESTful podem ser descritos através do OpenAPI, que é a iniciativa sobre a qual falaremos aqui. Além dos benefícios já citados, a descrição de uma API pode vir antes mesmo da construção da mesma, facilitando o planejamento e provendo diretrizes para a sua implementação.

A OpenAPI Initiative (OAI) tem como foco desenvolver um padrão “vendor neutral” para descrição de APIs. Começou com base no Swagger Specification, da SmartBear Software, e tem como integrantes players de peso tais como a Linux Foundation, Google, IBM, Atlassian e outros. Sua última versão é a 3.0.3. Há varias implementações do padrão, como os kits da Swagger, que contém um visualizador integrável a serviços, editor, geradores de código de bibliotecas e skeleton de servidores, bibliotecas integráveis a webservices que fazem varreduras dos endpoints e entradas nos comentários dos mesmos para gerar a descrição. Além disso, nos marketplaces de extensões das principais IDEs tais como Eclipse, VSCode e outros é possível encontrar plugins que auxiliam na edição e leitura de arquivos OpenAPI. Que podem ser em formato JSON ou YAML.

Vejamos como ficaria a descrição do nosso serviço utilizando OpenAPI 3.0.3 no formato YAML:

Descrição do serviço de registro de livros usando a OpenAPI 3.0.3.openapi: 3.0.1
info:
  title: Serviço de Livros
  description: Esta é a descrição de API do nosso serviço de registro de livros.
  version: "1.0"
tags:
- name: livro
  description: Everything about your livros
paths:
  /livro:
    get:
      tags:
      - livro
      summary: Listar todos os livros
      description: Retorna a lista de livros do sistema
      operationId: listar_livros
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    codigo:
                      type: string
                    titulo:
                      type: string
                    autor:
                      type: string
                    n_paginas:
                      type: integer
        400:
          description: Requisição inválida
          content: {}
    post:
      tags:
      - livro
      summary: Cadastrar um novo livro
      operationId: criar_livro
      requestBody:
        description: Objeto que representa o livro a ser inserido
        content:
          application/json:
            schema:
              type: object
              properties:
                codigo:
                  type: string
                titulo:
                  type: string
                autor:
                  type: string
                n_paginas:
                  type: string
        required: true
      responses:
        405:
          description: Entrada inválida
          content: {}
      x-codegen-request-body-name: body
  /livro/{codigo}:
    get:
      tags:
      - livro
      summary: Buscar livro por código
      description: Retorna o livro pelo código
      operationId: buscar_por_codigo
      parameters:
      - name: codigo
        in: path
        description: Código do livro a ser retornado
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  codigo:
                    type: string
                  titulo:
                    type: string
                  autor:
                    type: string
                  n_paginas:
                    type: integer
        400:
          description: Código inválido
          content: {}
        404:
          description: Livro não encontrado
          content: {}
    put:
      tags:
      - livro
      summary: Atualiza os dados de um livro
      description: Atualiza os dados de um livro pelo código
      operationId: atualizar_livro
      parameters:
      - name: codigo
        in: path
        description: Código do livro a ser atualizado
        required: true
        schema:
          type: string
      requestBody:
        description: Objeto que representa o livro a ser atualizado
        content:
          application/json:
            schema:
              type: object
              properties:
                codigo:
                  type: string
                titulo:
                  type: string
                autor:
                  type: string
                n_paginas:
                  type: string
        required: true
      responses:
        405:
          description: Invalid input
          content: {}
      x-codegen-request-body-name: body
    delete:
      tags:
      - livro
      summary: Exclui um livro
      description: Apaga um livro pelo código
      operationId: remove_livro
      parameters:
      - name: codigo
        in: path
        description: Código do livro a ser removido
        required: true
        schema:
          type: string
      responses:
        400:
          description: Código inválido
          content: {}
        404:
          description: Livro não encontrado
          content: {}

Geração da Biblioteca

Uma vez de posse da descrição de nossa API no formato OpenAPI, seja gerado automaticamente, seja escrito manualmente, podemos gerar o código da biblioteca para inserção em códigos de terceiros e permitir que estes integrem-se a nossa API.

A forma mais simples, a princípio, é utilizar o Swagger Editor, que pode ser instalado localmente, através de uma imagem Docker ou diretamente online através deste link.

Gerando código com Swagger Editor

Aspecto do Swagger Editor.

Primeiramente, importe a descrição através do menu File, onde você terá duas opções:

Aspecto do menu File do Swagger Editor.

A primeira, Import URL, permite que você insira o endereço URL do padrão, se ele estiver disponível na rede. Muito útil quando se tem padrões gerados automaticamente ou de documentações de terceiro. Quando a utilizamos, devemos garantir que o CORS esteja habilitado no servidor de origem.

Diálogo de importação através da URL.

A segunda opção é importar através de um arquivo presente no próprio computador.

Além disso, podemos ainda copiar o padrão de algum lugar e colar diretamente no editor.

Vamos, agora, em Generate Cliente e selecionamos a linguagem para a qual queremos gerar uma biblioteca de cliente. Será gerado um pacote .ZIP e poderemos baixar em nosso computador.

Conjunto de linguagens para a qual se pode gerar códigos através do Swagger Editor.

Embora este processo possibilite gerar bibliotecas de cliente para várias linguagens e frameworks, carece ainda de customizações, que necessitariam estar em metadados na própria descrição de API. Uma vez que os da biblioteca gerada (swagger_client) e dos métodos não são, por padrão, muito amigáveis. Mais informações sobre estas customizações estão aqui.

Gerando código com Open API Generator

O OpenAPI generator é um programa que pode ser utilizado através da linha de comando e oferece uma maior gama de personalizações do que o Swagger Editor. Está disponível para Linux, Windows, MacOS, Java JAR, NPM e podemos baixá-lo aqui:

• https://github.com/OpenAPITools/openapi-generator

Para instalação no Linux baseado em Debian, execute os comandos:

mkdir -p ~/bin/openapitools
curl https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/bin/utils/openapi-generator-cli.sh > ~/bin/openapitools/openapi-generator-cli
chmod u+x ~/bin/openapitools/openapi-generator-cli
export PATH=$PATH:~/bin/openapitools/

Neste tutorial, utilizaremos a versão JAR, mais portável. Baixe no seu computador:

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/4.3.0/openapi-generator-cli-4.3.0.jar -O openapi-generator-cli.jar

Após baixado, executamos o seguinte comando:

java -jar openapi-generator-cli-4.3.0.jar list

Com isso, podemos ver a diversidade de linguagens para a qual podemos gerar bibliotecas. Além disso, há a possibilidade de gerar aplicações de servidores, documentações e configurações, mas vamos deixar isso para outros artigos.

Agora vamos verificar, por exemplo, todas as opções de parâmetros possíveis de geração de bibliotecas para Java (poderia ser para qualquer outra linguagem listada no comando anterior).

java -jar openapi-generator-cli-4.3.0.jar config-help -g java

Dentre as opções listadas, é possível personalizar o nome do artefato (com.suaempresa.seuservico), licença, versão, etc. Além disso, podemos utilizar diversos frameworks para fazer consultas HTTP (seção library template). A escolha do framework ideal implica no grau de compatibilidade da biblioteca gerada com a aplicação de terceiros que irá integrar-se a sua aplicação. Por exemplo, o Spring, por exemplo, faz consultas utilizando o RestTemplate, por padrão. Utilizar outro framework implicaria em adicionar dependências no pom.xml ou build.gradle do seu projeto que poderiam, talvez, causar conflitos.

Vamos utilizar, então, o RestTemplate como biblioteca de consulta, ao invés do OkHTTP que vem por padrão. Execute o comando:

java -jar openapi-generator-cli-4.3.0.jar generate -i livro-api.yaml \
--api-package com.douglas.livros_service.api \
--model-package com.douglas.livros.model \
--invoker-package com.douglas.invoker \
--group-id com.douglas \
--artifact-id liblivros \
--artifact-version 0.0.1-SNAPSHOT \
-g java --library resttemplate -o liblivros

O código resultante pode ser tanto exportado com um pacote compilado .JAR quanto importado como código diretamente em outro projeto. Dentro da pasta, verificamos que foi gerado tanto um pom.xml quanto um build.gradle, isto é, permitindo a compilação tanto por Maven quanto por Gradle.

Vamos construir o nosso .JAR executando o seguinte comando dentro da biblioteca:

mvn clean install -Dmaven.javadoc.skip=true

Se o seu Java for versão 8 ou inferior, tudo ocorrerá bem. Caso contrário, haverá um problema devido a um bug relacionado a biblioteca javax.annotation. Para contornar este problema, no pom.xml adicione a seguinte dependência e execute novamente o comando anterior:

<!-- https://mvnrepository.com/artifact/javax.annotation/javax.annotation-api -->
<dependency>
    <groupId>javax.annotation</groupId>
    <artifactId>javax.annotation-api</artifactId>
    <version>1.3.2</version><!-- ou a versão mais atual -->
</dependency>

Está pronto. Dentro da pasta target você encontrará o seu pacote .JAR, neste exemplo o liblivros-0.0.1-SNAPSHOT-tests.jar, e poderá importar dentro de outra aplicação ou disponibilizá-la para terceiros o fazer.

Link da biblioteca gerada com a API: https://github.com/limadantas/exemplo_liblivros

Documentação oficial do OpenAPI Generator: https://openapi-generator.tech/docs/usage/