Review | OpenAPI: Beginner to Guru

6 min readMar 2, 2020

Como prometido, inicio hoje a review do curso OpenAPI: Beginner to Guru do John Thompson.

Demorei um pouco a mais para escrever porque tenho tentado escrever em três idiomas para tentar alcançar mais pessoas, e treinar um pouco mais meu inglês e espanhol. Já fiz cursos em espanhol e inglês, e quero melhorar minhas habilidades de comunicação.

Na verdade, longe de querer dizer que sou bom, gostaria de dizer que preciso melhorar, não me considero uma pessoa de vocabulário avançado, mas seguem meus motivos para escrever em mais de um idioma:

A primeira vez que viajei para os Estados Unidos estava bem preocupado em como falar ou o que as pessoas iriam pensar de mim, um brasileiro que não sabe falar direito. O que eu descobri é que as pessoas não se importam… não nesse nível de viagem… o importante é ser compreendido.

Passei então a mudar meu mindset e estou escrevendo em inglês com a ajuda do Grammarly, e em espanhol com a ajuda do Google Translator mesmo. Professores de idiomas, não me batam…

Na verdade, deixa eu melhorar um pouco meu argumento. Não acho que eu deva escrever qualquer coisa em outro idioma e que o importante é falar errado, não sou adepto da máxima de não corrigir as pessoas quando escrevem errado porque o importante é se comunicar.

Na verdade, acredito que entre tentar explicar algo errado, e não tentar por medo de escrever errado, vou ficar com a primeira opção, porém, você, meu caro leitor que gostar de me dar um feedback de como posso melhorar meu português, inglês ou espanhol, sua opinião é muito bem vinda. Assim, melhoro meu vocabulário.

Acredito que escrevendo melhor, alcançarei mais pessoas ainda. Se algum leitor espanhol tiver alguma dica de algo semelhante ao Grammarly e melhor que Google Translator para o idioma, me ajudaria muito.

Outro motivo pelo qual demorei a escrever é que criei uma Prova de Conceito (PoC) do ponto negativo que achei do curso do John Thompson. Você pode encontrar ela aqui no meu GitHub. Já que estamos falando de sugestão para melhorar como escrevo em uma língua, qualquer sugestão para melhorar minha escrita de código, o que não deixa de ser em uma linguagem, será bem vinda…

Tentei uma prática nova nesse repositório que eu já vi em outros projetos, ter Gradle e Maven no mesmo repositório, mas discutirei melhor isso no próximo post.

Vamos focar ao que interessa então…

Review | Sobre o autor

John Thompson, o Spring Guru, é um dos instrutore que como eu disse no post anterior, aguardo ansiosamente o lançamento de novos cursos.

Foi o caso desse curso de Open API 3.0. Eu já escrevia sobre Swagger e API First há algum tempo aqui, aqui, aqui e aqui. Era natural me perguntar sobre se valeria ou não a pena comprar esse curso do John Thompson.

Antes de falar do curso propriamente dito, gosto bastante da didática que o John tem, seus cursos são bem explicados e não seguem aquela abordagem de um tutorial sem aprofundar em pontos mais específicos. Resolvi dar uma chance para o curso por isso, não me arrependi, mas posso dizer que em um detalhe esperava mais… antes que o John fique com raiva de mim, na verdade, acredito que algo em mim como desenvolvedor esperava mais pelo código, mas falaremos mais sobre isso a seguir.

Caso você não conheça os cursos dele referente a stack Java e Spring em sua maioria, recomendo as seguintes formas de encontrá-lo:

Review | The good parts

Em um curso de pouco menos que 5 horas dividido em 52 aulas John Thompson abordou pontos bastante interessantes, e que me evoluíram como profissional focado em documentação de APIs e Microservices. Seguem então os principais pontos que achei interessante

OpenAPI 2.0 vs 3.0

Sem sobra de dúvidas a primeira parte que achei bem interessante do curso foi a lição OpenAPI 2.0 vs 3.0 em que mostrado a diferença entre as abordagens 2.0 e 3.0.

Pode não parecer muita coisa, mas quando fui desenvolver novos projetos na AIS Digital resolvi utilizar o OpenAPI 3.0 ao invés da abordagem que eu utilizava com o Swagger 2.0. Dentre as principais diferenças que senti foram content em responses e o uso de components ao invés de definitions. Nada tão disruptivo a princípio, mas me deu um pequeno nó na cabeça.

Segurança

Outro ponto que achei bem interessante no curso foi a parte de segurança em que John Thompson focou em questões como Basic Auth e JWT Bearer. Não é algo muito aprofundado, sobre isso falarei melhor na parte seguinte, mas te dá uma noção de como a camada de segurança se comporta.

Open API Generator

Sem sobra de dúvidas essa foi a melhor parte do curso para mim! John Thompson apresentou o site do Open API Generator, através dele você consegue encontrar as soluções em plugin para Gradle e Maven.

Até então eu usava o fantástico plugin do Swagger para Gradle do Hidetake Iwata! Escrevi sobre ele aqui.

Com ele é possível gerar implementações server-side e client-side de REST APIs em Swagger 2, Swagger 3 e OpenAPI. O desacoplamento entre as camadas de implementação e consumo é algo sensacional! As premissas em SOA já falavam sobre isso, e se posso dizer sobre uma filosofia de desenvolvimento que mais me marcou o pensamento seria essa.

Com o auxílio desse plugin é possível gerar server-sides em:

C#
Java Play
Java Spring-Boot
Java Vert.x
JAX-RS RestEasy
JAX-RS CXF
Kotlin Spring-Boot
Kotlin Vert.x
NodeJS
PHP
Ruby
Rust
Scala
Dentre outros

Assim como client-sides em:

C#
Clojure
Dart
Java Feign
Java Retrofit
Java Retrofit 2
Dentre outros

A lista completa se encontra aqui.

Resolvi testar o plugin novo apresentado pelo John. Na implementação que criei aqui utilizei os plugins do Gradle e Maven em um projeto Spring Boot com Kotlin. No projeto são geradas classes em Java com Spring para a camada server-side e Java com Retrofit 2 para a camada client-side.

As classes geradas estarão nas pastas build (Gradle) e target (Maven), e por tanto não estarão versionadas no projeto, porém, estarão no source set do projeto, com isso, essas classes podem ter interação no momento do desenvolvimento.

Esses e outros pontos discutiremos melhor no próximo post.

Outros pontos positivos

Também são abordadas questões referentes ao Swagger Hub e aulas sobre protocolo HTTP, JSON Schema, tipos de dados, enums, herança, parâmetros, dentre outras coisas.

Review | The bad parts

Fiquei na dúvida se classificaria isso como uma parte ruim, porque acredito que o objetivo do curso seja um overview mais aprofundado sobre o Open API 3.0, mas senti falta de dois pontos:

Modelos canônicos no Swagger Hub

Uma abordagem interessante é a reusabilidade de definições externas à OpenAPI em questão. Algo parecido com a abordagem de Modelos Canônicos em SOA, aonde era possível definir modelos de reuso em uma abordagem no Swagger Hub, por exemplo.

Open API Code Gen

Essa foi a parte que acredito que poderia ser melhor detalhada, apesar de bem explicada, daria para ter um curso focado só nessa parte e segurança e em como desenvolver APIs com API First, facilitando o desacoplamento da solução, o que facilitaria a evolução da API, por exemplo. É sobre esse ponto que falaremos no próximo post, assim que a Grammarly e o Google Translator fizerem seu trabalho de traduzir esse texto.

Creio que o ponto que mais senti falta foi o de abrir uma IDE e utilizar o plugin de geração de código, sendo exemplificadas vantagens e desvantagens de tal prática.

Conclusão

Mesmo com essas considerações negativas, isso não impactou em nada a minha avaliação do curso. Cinco estrelas!!!

Recomendo a todos que estão adentrando a esse mundo de documentação de APIs e implementação via paradigma API First.

John, continue a fazer esse trabalho excepcional!!!

Nos vemos no próximo post… até lá…