Revisión | OpenAPI: Beginner to Guru [ES]

6 min readMar 6, 2020

Como prometí, hoy empiezo a revisar el curso OpenAPI: Beginner to Guru del John Thompson.

Tardé un poco más en escribir porque he estado tratando de escribir en tres idiomas para tratar de llegar a más personas y entrenar un poco más mi inglés y español. Ya he tomado cursos en inglés y español, y quiero mejorar mis habilidades de comunicación.

Lejos de querer decir que soy bueno en esos idiomas, me gustaría decir que necesito mejorarlos, no me considero una persona con vocabulario avanzado, pero estas son mis razones para escribir en más de un idioma:

La primera vez que viajé a los Estados Unidos, me preocupaba mucho cómo hablar o lo que la gente pensaría de mí, un brasileño que no sabe hablar correctamente. Lo que descubrí es que a la gente no le importa. Lo importante es ser entendido.

Luego empecé a cambiar mi mentalidad y estoy escribiendo en inglés con la ayuda de Grammarly y en español con la ayuda de Google Translator. Profesores de idiomas, no me peguen.

Déjame mejorar un poco mi argumento. No creo que deba escribir nada en otro idioma y lo importante es comunicarme de manera incorrecta, no soy partidario de la máxima de no corregir a las personas cuando escriben mal porque lo importante es comunicarse.

De lo contrario, creo que si necesito elegir entre tratar de escribir algo de manera incorrecta y no tratar de escribir por miedo a escribirlo de manera incorrecta, tomo la primera opción. Sin embargo, usted, mi querido lector, puede darme su opinión sobre cómo puedo mejorar mi portugués, inglés o español. Tu opinión es muy bienvenida. Entonces, de esa manera, puedo mejorar mi vocabulario.

Creo que al escribir mejor, llego a más personas. Si algún lector español tiene algún consejo sobre algo similar a Grammarly y mejor que Google Translator para el idioma, me ayudaría mucho.

Otra razón por la que tardé tanto en escribir es que creé una Prueba de concepto (POC) desde el “punto negativo” que encontré en el curso de John Thompson. Puedes encontrarlo aquí en mi GitHub. Ya que estamos hablando de una sugerencia para mejorar la forma en que escribo en un idioma, cualquier sugerencia para mejorar la escritura de mi código, que también es un idioma, ¡sería fantástico!

Intenté una nueva práctica en este repositorio que he visto en otros proyectos, teniendo a Gradle y Maven en el mismo proyecto, pero lo discuto más adelante en la próxima publicación.

Centrémonos en lo que importa entonces.

Revisión | Sobre el Autor

John Thompson, el Spring Guru, es uno de los instructores que, como dije en el post anterior, espero nuevos cursos.

Había estado escribiendo sobre Swagger y API First por algún tiempo aquí, aquí, aquí y aquí, luego, cuando John anuncia el curso Open API 3.0, era natural preguntarme si valía la pena comprar este curso.

Antes de hablar sobre el curso en sí, me gusta la didáctica que tiene John, sus cursos están bien explicados y no siguen ese enfoque tutorial sin profundizar en los puntos avanzados. Decidí darle una oportunidad al curso y no me arrepentí, pero puedo decir que en un detalle esperaba más. Antes de que John se enojara conmigo, creo que como desarrollador esperaba más del código, sin embargo, hablaremos más sobre eso a continuación.

Si no conoce los cursos y tutoriales de John, le recomiendo las siguientes formas de encontrarlo:

Revisión | Las buenas partes

En poco menos de 5 horas divididas en 52 clases, John Thompson abordó puntos fascinantes, lo que me convirtió en un profesional enfocado en la documentación de API y microservicios. Aquí están los puntos principales que encontré interesantes.

OpenAPI 2.0 vs 3.0

Sin lugar a dudas, la primera parte que encontré muy interesante en el curso fue la lección OpenAPI 2.0 vs. 3.0 en la que se muestra la diferencia entre los enfoques 2.0 y 3.0.

Puede que no parezca mucho, pero cuando fui a desarrollar nuevos proyectos en AIS Digital, decidí usar OpenAPI 3.0 en lugar del enfoque que usé con Swagger 2.0. Entre las principales diferencias, sentí que había content en las respuestas y el uso de components en lugar de definitions. Al principio, nada tan perturbador, pero al principio me dio un poco de confusión.

Seguridad

Otro punto que encontré muy interesante en el curso fue la parte de seguridad en la que John Thompson se enfocó en temas como Basic Auth y JWT Bearer. No es algo muy profundo, hablo más sobre esto en la siguiente parte, pero le da una idea de cómo se comporta la capa de seguridad.

Open API Generator

¡Sin duda, esta fue la mejor parte del curso para mí! John Thompson presentó el sitio web Open API Generator, a través del cual puede encontrar soluciones de complementos para Gradle y Maven.

¡Hasta entonces, usé el fantástico plugin de Swagger Gradle de Hidetake Iwata! Escribí sobre eso aquí.

Con él, es posible generar implementaciones del lado del servidor y del lado del cliente de las API REST en Swagger 2, Swagger 3 y OpenAPI. ¡El desacoplamiento entre las capas de implementación y consumo es algo sensacional! Las suposiciones en SOA ya hablaron sobre esto, y si puedo decir sobre una filosofía de desarrollo que marcó más mi pensamiento, eso sería todo.

Con la ayuda de este complemento, es posible generar lados del servidor en:

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
Entre otros

Además del lado del cliente en:

C#
Clojure
Dart
Java Feign
Java Retrofit
Java Retrofit 2
Entre otros

La lista completa está aquí.

Decidí probar el nuevo complemento presentado por John. En la implementación que creé aquí, utilicé los complementos de Gradle y Maven en un proyecto Spring Boot con Kotlin. En el proyecto, las clases se generan en Java con Spring para la capa del lado del servidor y Java con Retrofit 2 para la capa del lado del cliente.

Las clases generadas están en las carpetas build (Gradle) y target (Maven), y por lo tanto no están versionadas en el proyecto. Sin embargo, están en el source set del proyecto; con eso, estas clases pueden tener interacción en el momento del desarrollo.

Estos y otros puntos se discuten más adelante en la próxima publicación.

Otros buenos puntos

También se abordan cuestiones relacionadas con Swagger Hub y clases sobre protocolo HTTP, esquema JSON, tipos de datos, enumeraciones, herencia, parámetros, entre otras cosas.

Revisión | Las partes malas

Estaba en duda si clasificaría esto como una mala parte porque creo que el objetivo del curso es una descripción más profunda de Open API 3.0, pero hablaré de dos puntos:

Modelos canónicos en el Swagger Hub

Un enfoque interesante es la reutilización de definiciones externas a la Open API. Algo similar a los enfoques de los modelos canónicos en SOA, donde fue posible definir modelos de reutilización en un enfoque en el Swagger Hub, por ejemplo.

Código API abierto Gen

Esta fue la parte que creo que podría ser mejor detallada. Aunque bien explicado, sería posible tener un curso enfocado solo en esa parte y seguridad y en cómo desarrollar API con API First, facilitando el desacoplamiento de la solución, lo que facilitaría la evolución de la API, por ejemplo. De esto es de lo que hablamos en la próxima publicación, una vez que Grammarly y Google Translator hagan su trabajo de traducir ese texto.

Creo que lo que más me perdí fue abrir un IDE y usar el complemento de generación de código, con ejemplos de las ventajas y desventajas de tal práctica.

Conclusión

Incluso con estas consideraciones negativas, no tuvo impacto en mi evaluación del curso. ¡¡¡Cinco estrellas!!!

Se lo recomiendo a todos los que ingresan a este mundo de documentación e implementación de API a través del paradigma API First.

¡John, sigue haciendo este trabajo excepcional!