OpenAPI & Generador de Servicios
Script de Node opcional proporcionado por separado del cliente HTTP principal. Se utiliza solo al generar tipos de TypeScript y archivos de servicio desde OpenAPI/Swagger JSON.
Función opcional: no necesaria para el uso de Core
Los usuarios generales de @byeolnaerim/typed-rx-http, /next o /rsocket no necesitan ejecutar este script ni instalar openapi-typescript en su proyecto.
Aislamiento de dependencia openapi-typescript
La generación de tipos OpenAPI requiere el CLI openapi-typescript, pero el paquete no lo incluye en las dependencias generales. Las devDependencies.typescript de typed-rx-http mantienen la versión de TypeScript 6.0.3 y solo utilizan un entorno temporal npx en el script de nodo automático de OpenAPI.
En la etapa básica de generación de OpenAPI, se ejecutan openapi-typescript y [email protected] juntos, por lo que no se cambia ni se utiliza la versión de TypeScript/openapi-typescript instalada en el proyecto del usuario.
Si es necesario, se puede fijar el comando completo en openApiTypescriptCommand.
O también se puede cambiar solo la versión del paquete que configura el comando básico.
Primero: preparar el archivo del proyecto al que apuntará commonServiceFile
Antes de que commonServiceFile aparezca en el ejemplo del generador, debe entender este archivo. commonServiceFile es la ruta del archivo de propiedad del proyecto que importa las funciones HTTP comunes del servicio generado, no es una opción que crea un archivo. El nombre del archivo puede ser rxjsHttpService.ts, commonService.ts, etc.
Código completo mínimo
El siguiente archivo crea una vez createHttpClient en el proyecto y exporta callApi y callApiStream para su reutilización en el servicio generado. Si no se necesita caché o autenticación de sesión, se puede comenzar con esta estructura.
rxjsHttpService.ts
tsCódigo completo que incluye caché de sesión/CSR/SSR
Para que el servicio generado use callApiClientCache o callApiServerCache, o para manejar de manera común los encabezados por solicitud y la autenticación de sesión en Next.js, se expande a la siguiente forma completa.
rxjsHttpService.ts
tsMétodo de ejecución
Archivos generados
La configuración predeterminada genera los siguientes archivos.
apiUnionArrays.tsgenera no solo el enum del esquema OpenAPI, sino también un arreglo de constantes de solo lectura para los enums de parámetros de consulta, ruta, encabezado y cookie, y también maneja los items.enum de los parámetros de consulta en arreglo.
Opcional: conectar Swagger del backend con commonService del proyecto
A partir de aquí, se muestra un ejemplo de cómo conectar el generador con un proyecto real. WebFlux/webflux-fe-dev-assistant es solo una forma de proporcionar Swagger y no es una dependencia obligatoria.
Preparar la documentación Swagger
Swagger puede ser Springdoc, otra herramienta OpenAPI o un archivo escrito manualmente. Si se utiliza un endpoint funcional de WebFlux, webflux-fe-dev-assistantTambién se puede utilizar el método de proporcionar la documentación Swagger.
Ejemplo de generación especificando opciones en el proyecto
Se pueden especificar el endpoint del backend, la ruta swagger.json a guardar, la ruta de salida de tipos/servicios y commonServiceFile según la estructura del proyecto.
generateSwagger.cjs
jsEn entornos donde no se puede recibir documentación por HTTP, se puede utilizar junto con las mismas opciones de salida. generateSwaggerFromFilese puede utilizar.
commonServiceFile es la ruta de importación
commonServiceFilees la ruta del archivo de propiedad del proyecto que importa callApi, callApiStream y el envoltorio de caché del servicio generado. No es una opción que genere o sobrescriba este archivo.
ApiBusinessService.ts
tsEjemplo de cómo se colocan los resultados de generación en el proyecto
El archivo público designado como commonServiceFile, como rxjsHttpService.ts, es gestionado directamente por el proyecto. Los resultados bajo auto y @types/auto se regeneran cuando el documento cambia.
Reglas de nombre de archivo y función
El nombre del archivo de servicio se determina por los dos primeros segmentos de la URL, y el nombre de la función se determina a partir del tercer segmento en adelante. Las variables de ruta se incluyen en el nombre de la función en forma de By + PascalCase.
GET /api/business/workplaces/search
ApiBusinessService.ts → workplacesSearch({ params })
GET /api/business/workplaces/{id}
ApiBusinessService.ts → workplacesById({ path })
GET /api/orders/history/search
ApiOrdersService.ts → historySearch({ params })
POST /oauth2/login
Oauth2LoginService.ts → post({ body })
Argumentos de llamada de la función de generación
GeneratedServiceUsage.tsx
tsxLa clave del parámetro de consulta del servicio generado es params, la variable de ruta es path, y el cuerpo de la solicitud es body. Dentro de la función de generación, se convierten en ServiceArguments de queryString, pathVariable y body respectivamente.