Header Ads Widget

Ticker

6/recent/ticker-posts

Introducción al generador OpenAPI

 


En los últimos años, uno de los paradigmas de desarrollo más populares es la práctica de generación automática. La idea de poder conectar su código o archivos de documentación en algún tipo de “traductor universal” futurista para crear hermosos stubs, clientes y otros resultados es, en muchos sentidos, el sueño final de muchos desarrolladores multiplataforma. Como tal, las soluciones que prometen unificar las bases de código y ofrecer resultados interoperables a menudo se consideran la "próxima gran novedad".

Hoy, veremos una de esas ofertas para documentación de generación automática y otros recursos para desarrolladores. OpenAPI Generator promete ser una herramienta con una extensibilidad extrema y paradigmas compatibles. ¿Hace bien algo de esto? Vamos a ver.

¿Qué es OpenAPI Generator?

OpenAPI Generator puede generar automáticamente clientes, servidores y documentación a partir de documentos OpenAPI 2.0 / 3.x. Ver el repositorio de Github .

OpenAPI Generator es una herramienta diseñada para crear bibliotecas cliente API, stubs de servidor, configuraciones y documentación de documentos OpenAPI 2.0 y 3.x. Cuenta con una amplia gama de funciones y es utilizado por una amplia gama de usuarios, algunos de los cuales también son mantenedores. OpenAPI Generator se centra en la facilidad de uso; se posiciona como una herramienta para reducir la carga de nuevos desarrollos y tecnologías a través de la integración y el aprovechamiento de documentos OpenAPI.

En particular, OpenAPI Generator es una bifurcación de swagger-codegen entre las versiones 2.3.1 y 2.4.0. Por esta razón, muchos de los conceptos fundamentales y las ofertas que subyacen a OpenAPI Generator deberían resultarle familiares. La bifurcación se produjo por varias razones, como se detalla en la documentación del Generador de OpenAPI. En su mayoría, se reducen a la simplicidad en la función, la reducción en el desarrollo de sucursales simultáneas y una mayor propiedad de la comunidad. Esta participación de la comunidad es significativa y es una parte importante del espíritu de OpenAPI Generator.

Caracteristicas

OpenAPI Generator afirma tener muchas características, pero la que parece valorar más es su simplicidad. OpenAPI Generator admite más de 50 generadores de clientes, lo que lo hace bastante extensible; esto es muy importante, ya que elimina un gran paso hacia la adopción al proporcionar una amplia compatibilidad y soporte. Además, OpenAPI Generator tiene un conjunto bastante sólido de opciones de personalización, lo que permite aprovechar casi cualquier entorno de proyecto. Como una extensión de esta escalabilidad, extensibilidad y personalización dobladas, OpenAPI Generator también admite una amplia gama de esquemas y configuraciones. Cuenta con generadores individuales (configuración Apache2, MySQL, GraphQL) y más generadores especialmente diseñados basados ​​en código derivado.

También existen herramientas de desarrollo de servidor, suponiendo que utilice uno de los más de 40 idiomas que admiten. Curiosamente, la documentación señala que algunos de los generadores de stub del servidor admiten "Inversión de control". Este principio es una inversión de la relación código / instancia en el desarrollo clásico y crea una capa entre su base de código y la instancia que genera. Debido a que la instancia generada existe separada del código subyacente, puede actualizar el código sin romper toda la instancia.

Por supuesto, un atractivo principal para el generador es el hecho de que genera documentación además de todos los stubs y clientes del servidor. Esto tiene sentido dadas sus raíces Swagger, y puede parecer una pequeña adición, pero la documentación es increíblemente importante. Hemos discutido la importancia de la documentación varias veces anteriormente, pero dadas las capacidades de OpenAPI Generator, su soporte para Inversión de Control, etc., tiene aún más sentido en este caso.

A continuación se muestra una muestra de clientes API compatibles, stubs de servidor, generadores de documentación y tipos de contenido / archivos generales. Para obtener una lista más exhaustiva, consulte GitHub para OpenAPI Generator .

OpenAPI Generator admite:

  • Bash, C #, C ++, Clojure, Erlang, Go, Haskell, Java, Lua, Node.js, Perl, PHP, Python, Ruby, Rust, Swift y otros clientes API.
  • Ada, F #, Kotlin, Python, NodeJS, Ruby, Rust, Scala y otras bases de código de instancia de servidor.
  • HTML, Confluence Wiki y Asciidoc para la generación de documentación API.

Lea también: Guía definitiva para más de 30 soluciones de documentación

Usando OpenAPI Generator

Para demostrar cómo podría existir OpenAPI Generator en un flujo de trabajo común, hagamos referencia a la implementación de Maven .

Instalación

Para comenzar, simplemente agregue el complemento Maven a la sección "compilación-> complementos" del código base:


org.openapitools openapi-generator-maven-plugin 4.2.3 generate ${project.basedir}/src/main/resources/api.yaml java src/gen/java/main

A continuación, invoque la función de compilación usando "mvn clean compile". Desde aquí, podemos comenzar a configurar nodos en pares clave / valor usando la estructura configuración / opción / clave / valor:


    

En esta estructura, cada configuración tiene una opción y un par clave / valor: la opción es un valor establecido como se define a través de la lista de parámetros de configuración general dentro de la documentación de Maven, y el par clave / valor son los valores específicos dados a esa opción. . Como ejemplo, supongamos que queríamos crear un modelo que emparejara Usuarios con Locale. Podríamos hacer esto indicando la siguiente configuración:


    
       User,Locale
    

Generadores personalizados

Una advertencia a este enfoque al que se hace referencia varias veces en la documentación de OpenAPI Generator es el hecho de que los generadores personalizados en esta implementación no son compatibles con classpath: / synatx. En cambio, todo debe indicarse explícitamente, desde el paquete (debe ser el nombre del paquete totalmente calificado) hasta las plantillas personalizadas llamadas. Esto significa que los generadores personalizados deben desarrollarse con direccionamiento abiertamente explícito. Como ejemplo, OpenAPI Generator proporciona el siguiente generador personalizado en la documentación:


org.openapitools openapi-generator-maven-plugin ${openapi-generator-maven-plugin-version} generate ${project.basedir}/src/main/resources/yaml/yamlfilename.yaml com.my.package.for.GeneratorLanguage myTemplateDir ${project.build.directory}/generated-sources ${default.package}.handler ${default.package}.model ${default.package}.handler com.my.generator customgenerator 1.0-SNAPSHOT

Usando un generador

Ahora que hemos creado un generador, podemos instalarlo:

Mvn clean install -f out/generators/my-codegen

Y con esto, hemos usado nuestro generador, es realmente así de simple.

Posibles advertencias

OpenAPI Generator es muy poderoso y tiene una amplia gama de lenguajes y enfoques compatibles. Dicho esto, hay algunas advertencias que deben tenerse en cuenta al usarlo en el flujo de trabajo promedio. Estos no son necesariamente "factores decisivos", pero agregan un contexto más amplio al caso de uso promedio.

La primera advertencia importante que debe tenerse en cuenta es que OpenAPI Generator sigue siendo, esencialmente, una bifurcación de herramientas centradas en Swagger. Debido a esto, hereda muchas de las debilidades de una solución autogenerada. La generación automática de cualquier cosa ahorra mucho tiempo, pero solo es tan buena como lo que se introduce en ella. Si bien esto parece obvio, el efecto secundario de un sistema de este tipo es que el código que de otra manera parece funcionar perfectamente dentro de su implementación dada, de hecho, puede resultar en código roto o stubs al generarlo.

Esto no sucede con la codificación manual porque las inconsistencias en el código a menudo son internamente inconsistentes; aunque esto no es ideal, al menos entrega un primer borrador viable de un proyecto y no requiere la perfección desde el principio. Si bien OpenAPI Generator es bastante flexible en este sentido, sigue siendo una solución automatizada y, como tal, requiere una implementación perfecta para generar código compatible que funcione al 100% dentro de las expectativas. Si bien esto es ciertamente una falla del desarrollador, y no de OpenAPI Generator, sí significa que la curva de aprendizaje puede, a veces, parecer más pronunciada que si el flujo de trabajo de codificación se hiciera manualmente.

Sin embargo, incluso si su código inicial es bueno, existe el hecho de que OpenAPI Generator depende del desarrollo y las implementaciones guiadas por la comunidad para generadores de código que no siempre son maduros. Para algunos usuarios, esto puede resultar en generadores que producen código inutilizable, o código que en teoría debería ser utilizable mientras que en la práctica se comporta de manera impredecible.

Dicho todo esto, OpenAPI Generator es un buen ejemplo de una solución generalista que agrega un gran valor que, en ciertos flujos de trabajo, puede tratarse mejor a través de una solución especializada. Si una base de código usa un lenguaje o paradigma relativamente específico y de nicho, puede ser mejor usar una solución diferente (o al menos tener en cuenta la relativa inmadurez del módulo OpenAPI Generator en cuestión). Sin embargo, como solución generalista, OpenAPI Generator es una herramienta maravillosa. Más específicamente, OpenAPI Generator es una herramienta de aceleración: probablemente no lo llevará al 100% a donde desea ir, pero hará el 90% del trabajo y expondrá hacia dónde debe dirigirse el resto del trabajo.

Conclusión

En última instancia, cualquier solución automatizada dependerá en gran medida de su caso de uso específico. Si bien OpenAPI Generator acerca la mayoría de los escenarios a tener clientes y servidores utilizables, algunas personas buscan implementaciones 100% perfectas. OpenAPI Generator puede entregar código perfecto en el primer intento, pero también es poco probable que lo haga repetidamente para cada idioma que se le lanza.

En consecuencia, OpenAPI Generator es una solución maravillosa en un caso de uso generalista. Si se necesita un caso de uso más especializado, no es la mejor opción del mundo, pero sigue siendo útil.

¿Qué opinas sobre OpenAPI Generator? ¿Qué podría mejorarlo? ¿Es una herramienta generalista adecuada? Háganos saber en los comentarios a continuación.

Recursos adicionales

  • Página de inicio de OpenAPI Generator
  • Generador OpenAPI en Github
  • OpenAPI.tools
  • Una guía para principiantes sobre la generación de código para API REST (generador OpenAPI) por William Cheng

Publicar un comentario

0 Comentarios