tsoa-next

Pronunciado así·uh

OpenAPI- compatible con REST APIs TypeScript y Node

Origen del proyecto

tsoa-next continúa el original tsoa proyecto. El repositorio original y sus colaboradores establecieron el establo TypeScript- primero y OpenAPI- la primera base en la que se basa este trabajo. Cuando las notas de liberación histórica o referencias migratorias todavía apuntan hacia arriba, se mantienen intencionalmente para la procedencia.

Objetivo

• TypeScript controladores y modelos como la única fuente de verdad para su API
• Una válida OpenAPI (antes Swagger) 2.0, 3.0 o 3.1 espectro se genera de sus controladores y modelos, incluyendo:
  • Caminos (por ejemplo: Obtener /usuarios)
  • Definiciones basadas en TypeScript interfaces (modelos)
  • Parámetros y propiedades modelo marcadas según sea requerido o opcionalmente TypeScript (e.g. myProperty?: la cadena es opcional en OpenAPI e)
  • jsDoc compatible con descripciones de objetos (la mayoría de otros metadatos pueden ser inferidos de TypeScript tipos)
• Las rutas se generan para el middleware de elección
  • Express, Hapi, y Koa actualmente compatible, otro middleware puede ser soportado usando una plantilla de manillar simple
  • Pagos de solicitud de validación

Filosofía

• Rely on TypeScript anotaciones de tipo para generar metadatos API si es posible
• Si las anotaciones de tipo regular no son una forma adecuada de expresar metadatos, use decoradores
• Utilice jsdoc para metadatos de texto puro (por ejemplo, descripciones de puntos finales)
• Minimizar la caldera
• Los modelos están mejor representados por interfaces (estructuras de datos puras), pero también pueden ser representados por clases
• Validación del tiempo de ejecución tsoa-next debe comportarse lo más cerca posible a las especificaciones que el generado OpenAPI schema describe. Cualquier diferencia en la lógica de validación se aclara mediante advertencias de registro durante la generación de la OpenAPI Especificación (OEA) y/o rutas.
  • Tenga en cuenta que ha permitido OpenAPI 3.0 o 3.1 minimizas las posibilidades de la lógica de validación divergente ya que las formas de esquema más nuevas son más expresivas que OpenAPI 2.0.

Lista de características

• Generar OpenAPI 2.0, 3.0 o 3.1 documentos directamente desde su TypeScript controladores, modelos y JSDoc comentarios.
• Treat TypeScript controladores y modelos como fuente de verdad para caminos, parámetros, esquemas, ejemplos, etiquetas y metadatos de seguridad.
• Generar controladores de ruta específicos para marco Express, Koa, y Hapi, o suministrar su propio Handlebars plantillas para tiempos de ejecución personalizados.
• Validar la entrada de solicitud en tiempo de ejecución con coacción configurable y manejo adicional-propiedad que permanece alineado con el esquema generado.
• Expose controlador-local spec endpoints with @SpecPath(...) sin leer un archivo de espectro generado del disco local a la hora de solicitud.
• Servir incorporado json, yaml, swagger, redoc, y rapidoc objetivos de especificaciones, con los paquetes de IU de docs cargados perezosamente como pares opcionales cuando está disponible.
• Adjuntar múltiples @SpecPath(...) decoradores al mismo controlador siempre y cuando sus caminos resueltos sean únicos.
• Cache respuestas de espectro incorporadas o personalizadas con 'none', en proceso 'memory', o un manejador de caché personalizado que puede leer de cadenas o arroyos.
• Vuelva o string o Readable respuestas de las @SpecPath(...) manipuladores para la documentación a medida o integraciones aguas abajo.
• Uso @Validate(...) para delegar la validación de plazos de ejecución para apoyar bibliotecas de esquemas externos tales como zod, joi, yup, superstructo io-ts.
• Personalizar la traducción de validación y el formato de fallo mediante el contexto de validación opcional aceptado por generado RegisterRoutes(...) funciones.
• Soporta ganchos de autenticación, inyección de dependencia, equipos de respuesta alternativos, cargas de archivos, middleware personalizado y flujos de trabajo de validación personalizada.
• Usar el tsoa CLI para la generación de espectros y rutas, o llame a las APIs programáticas de tsoa-next/cli.
• Objetivo moderno Node.js liberaciones con la política de apoyo verificada en CI en los LTS anteriores, LTS actual y Node VNext.

Primeros pasos

• Requisitos:
  • Node.js 22 o más
  • npm 10 o más
  • Verificamos el soporte en los LTS anteriores, LTS actual y Node vSiguiente en CI
• Documentación
• Referencia de API
• Guía de inicio

API del paquete

• Decoradores de importación, ayudantes de ejecución y soporte de ruta generados por tsoa-next
• Importar API de generación programática de tsoa-next/cli
• Usar el tsoa binario para CLI comandos de generación

Ejemplos

Echa un vistazo a las guías

Usa el repositorio de playground complementario para aplicaciones de ejemplo ejecutables y escenarios centrados en el servidor.

Consulta controladores de ejemplo en las pruebas

Consulta modelos de ejemplo en las pruebas

Se busca ayuda

Contribuir código

Para contribuir (mediante un PR), consulta primero la Guía de contribución

Contributors

No contributors

Changelog

No recent changes