ODS API
Descripción general
Las ODS APIs son API first, lo que significa que las especificaciones de API son el código fuente definitivo. Se genera código a partir de estas especificaciones cuando es posible, p. ej., el andamiaje de los controladores de Spring y los tipos de modelo. Este enfoque de "specification first" nos permitirá utilizar OpenAPI tooling, no solo para la generación de código, sino para cosas como testing, generación de servidores mock y descubrimiento de APIs.
Se definen dos APIs, ODS Ingestion y ODS Inquiry. Estas APIs son servidas por las aplicaciones ODS, que actualmente, y por coincidencia, se mapean uno a uno. La aplicación ODS Ingestion admite solo la ODS Ingestion API, y la aplicación ODS Inquiry admite solo la ODS Inquiry API.
Estructura del proyecto
Este proyecto está dividido en dos módulos principales, ods-ingestion y ods-inquiry, cada uno con su propia especificación de API y cada uno documentado por separado en las secciones correspondientes.
La intención inicial era que este proyecto contuviera solo las especificaciones OpenAPI y las clases de modelo generadas, pero desde entonces ha crecido para incluir el andamiaje de los controladores de Spring generados, las implementaciones de los controladores de Spring, el código de cliente, la validación y el código de soporte de pruebas. Algunos beneficios de este enfoque son
-
Confianza de que el código del cliente funciona correctamente con el código de back-end de Spring
-
Ciclo de retroalimentación más rápido al desarrollar nuevas funcionalidades de API o realizar cambios en el cliente y/o el código de back-end
-
Las cosas que cambian juntas se agrupan juntas
-
La implementación del controlador de Spring esencialmente forma parte de la API, y los cambios que pueden ser disruptivos es más probable que se identifiquen aquí
Generación de código
Este proyecto utiliza generación de código, específicamente openapi-generator, para generar código Java a partir de las especificaciones OpenAPI. La generación de código para cada API se documenta por separado, pero generalmente sigue un proceso de dos pasos.
-
Generar los tipos de modelo (POJOs) y empaquetarlos con cualquier código no generado
-
Generar el andamiaje de los controladores de Spring y empaquetarlo con las implementaciones de los controladores
Cada paso suele estar en su propio módulo, p. ej., un módulo api que contiene los tipos de modelo y un módulo spring que contiene el código del controlador.
OpenAPI Generator admite diferentes back-ends de generadores. Para código Java se utiliza el generador spring, generando los tipos de modelo y el andamiaje de los controladores de Spring.
Se utiliza el back-end openapi para generar una única especificación json tanto para Inquiry como para Ingestion. Esto significa que las especificaciones yaml fuente pueden dividirse en muchos archivos más pequeños para facilitar el desarrollo, mientras que aún se publica una única especificación para su uso posterior. Se genera código Typescript a partir de la especificación única de Inquiry para el Operational Dashboard.