Review | OpenAPI: Beginner to Guru [EN]

6 min readMar 3, 2020

As promised, today I start to review the OpenAPI: Beginner to Guru John Thompson's course.

I took a little longer to write because I have been trying to write in three languages to try to reach more people and to train my English and Spanish a little more. I have already taken courses in English and Spanish, and I want to improve my communication skills.

Far from wanting to say that I am good at those languages, I would like to say that I need to improve them, I do not consider myself an advanced vocabulary person, but here are my reasons for writing in more than one language:

The first time I traveled to the United States, I was very concerned with how to speak or what people would think of me, a Brazilian who does not know how to speak correctly. What I found out is that people don’t care. The important thing is to be understood.

Then I started to change my mindset, and I’m writing in English with the help of Grammarly and in Spanish with the help of Google Translator. Language teachers, don’t hit me.

Let me improve my argument a little. I don’t think I should write anything in another language and the important thing is to communicate in a wrong way, I am not a supporter of the maxim of not correcting people when they write wrong because the important thing is to communicate.

Otherwise, I believe that if I need to choose between trying to write something in a wrong way, and not trying to write for fear of writing it in a wrong way, I take the first option. However, you, my dear reader, can give me feedback on how I can improve my Portuguese, English, or Spanish. Your opinion is very welcome. So, that way, I can improve my vocabulary.

I believe that by writing better, I reach even more people. If any Spanish reader has any tips on something similar to Grammarly and better than Google Translator for the language, it helps me a lot.

Another reason I took so long to write is that I created a Proof of Concept (POC) from the “negative point” I found from John Thompson’s course. You can find it here on my GitHub. Since we are talking about a suggestion to improve how I write in a language, any suggestion to improve my code writing, which is also a language, it would be fantastic!!!

I tried a new practice in this repository that I have seen in other projects, having Gradle and Maven in the same project, but I discuss this further in the next post.

Let’s focus on what matters then.

Review | About the author

John Thompson, the Spring Guru, is one of the instructors who, as I said in the previous post, I look forward to new courses.

I had been writing about Swagger and API First for some time here, here, here and here, then, when John announces Open API 3.0 course, it was natural to ask me if it was worth buying this course.

Before talking about the course itself, I like the didactic that John has, his courses are well explained and do not follow that tutorial approach without delving into advanced points. I decided to give the course a chance, and I didn’t regret it, but I can say that in one detail I expected more. Before John got mad at me, I believe that as a developer I expected more from the code, however we’ll talk more about that below.

If you do not know John's courses and tutorials, I recommend the following ways to find him:

Review | The good parts

In just under 5 hours divided into 52 classes, John Thompson addressed fascinating points, which evolved me as a professional focused on documentation of APIs and Microservices. Here are the main points that I found interesting.

OpenAPI 2.0 vs 3.0

Without a doubt, the first part that I found very interesting in the course was the OpenAPI 2.0 vs. 3.0 lesson in which the difference between the 2.0 and 3.0 approaches shown.

It may not seem like much, but when I went to develop new projects at AIS Digital, I decided to use OpenAPI 3.0 instead of the approach I used with Swagger 2.0. Among the main differences, I felt were content in responses and the use of components instead of definitions. Nothing so disruptive at first, but it gave me a little confusion at the beginning.

Security

Another point that I found very interesting in the course was the security part in which John Thompson focused on issues such as Basic Auth and JWT Bearer. It is not something very in-depth, I talk more about this in the next part, but it gives you a sense of how the security layer behaves.

Open API Generator

Without a doubt, this was the best part of the course for me! John Thompson introduced the Open API Generator website, through which you can find plugin solutions for Gradle and Maven.

Until then, I used Swagger’s fantastic Gradle plugin from Hidetake Iwata! I wrote about it here.

With it, it is possible to generate server-side and client-side implementations of REST APIs in Swagger 2, Swagger 3, and OpenAPI. The decoupling between the layers of implementation and consumption is something sensational! The assumptions in SOA already talked about this, and if I can say about a development philosophy that most marked my thinking, that would be it.

With the aid of this plugin, it is possible to generate server-sides in:

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
Among others

As well as client-sides in:

C#
Clojure
Dart
Java Feign
Java Retrofit
Java Retrofit 2
Among others

The complete list is here.

I decided to test the new plugin presented by John. In the implementation I created here, I used Gradle and Maven plugins in a Spring Boot project with Kotlin. In the project, classes are generated in Java with Spring for the server-side layer and Java with Retrofit 2 for the client-side layer.

The generated classes are in the build (Gradle) and target (Maven) folders, and therefore they are not versioned in the project. However, they are in the project’s source set; with that, these classes can have interaction at the time of development.

These and other points are discussed further in the next post.

Other good points

Issues related to Swagger Hub and classes on HTTP protocol, JSON Schema, data types, enums, inheritance, parameters, among other things, are also addressed.

Review | The bad parts

I was in doubt if I would classify this as a bad part because I believe the objective of the course is a more in-depth overview of Open API 3.0, but I missed two points:

Canonical models in the Swagger Hub

An interesting approach is the reusability of external definitions to the Open API in question. Something similar to the Canonical Models approaches in SOA, where it was possible to define reuse models in an approach in the Swagger Hub, for example.

Open API Code Gen

This was the part that I believe could be better detailed. Although well explained, it would be possible to have a course focused only on that part and security and on how to develop APIs with API First, facilitating the decoupling of the solution, which would facilitate the evolution of the API, for example. This is what we talk about in the next post, once Grammarly and Google Translator does their job of translating that text.

I believe that the point I missed most was opening an IDE and using the code generation plugin, with examples of the advantages and disadvantages of such a practice.

Conclusion

Even with these negative considerations, it had no impact on my evaluation of the course. Five stars!!!

I recommend it to everyone who is entering this world of API documentation and implementation via API First paradigm.

John, keep doing this exceptional job !!!