Tipar automáticamente Swagger/OpenAPI endpoints con NSwag

• Tipar automáticamente Swagger/OpenAPI endpoints con NSwag
  • ¿Qué es NSwag?
  • ¿Qué necesitas?
  • Instalación
  • Configuración
  • Generar Interfaces
  • Final
  • Redes

Si alguna vez has tenido que tipar las respuestas de tus endpoints, sabrás que muchas veces es una tarea bastante difícil y larga. ¿Te imaginas poder hacerlo de manera automática y en pocos segundos? En este artículo, te explicaré cómo usar NSwag y cómo prepararlo para añadirlo a tus proyectos frontend.

¿Qué es NSwag?

NSwag es una herramienta muy flexible que nos permite tipar automáticamente clientes API a partir del archivo de definición de OpenAPI, de una manera clara y precisa. Es especialmente útil para endpoints de cierta envergadura.

¿Qué necesitas?

NSwag está creado en C#, por lo tanto, necesitarás tener instalado el Framework .NET completo 4.6.2+ o .NET 6.0+ en tu sistema. Al instalar el paquete npm, se verificarán los requisitos necesarios y, en caso de faltar alguno, se te proporcionará un enlace directo a la web oficial de Microsoft, así que no te preocupes por eso.

Por supuesto, también necesitarás disponer de un Endpoint que cumpla con los estándares de Swagger/OpenAPI 2.0. Normalmente, estos archivos de definición Swagger se encuentran en la página de Swagger de tu endpoint, justo debajo del título.

Nos interesa el archivo .json que contiene toda la documentación de nuestro backend y con el que NSwag va a trabajar.

También disponemos de una interfaz gráfica para realizar la configuración, pero en nuestro caso nos vamos a enfocar en la generación manual a través de comandos, para así poder añadirlo al flujo de automatización.

Instalación

Ahora vamos a añadir este paquete a nuestro repositorio. Dado que esta herramienta es una ayuda al desarrollo y no tiene impacto en la versión final del cliente, la añadiremos a las dependencias de desarrollo.

npm install nswag --save-dev

Durante el proceso de instalación, si no tienes instalado el framework .NET necesario (como el Framework .NET completo 4.6.2+ o .NET 6.0+), el asistente te pedirá que lo instales. También proporcionará un enlace directo a la web oficial de Microsoft para que puedas descargarlo e instalarlo fácilmente.

Configuración

La herramienta va a consumir un archivo tipo config.nswag dónde añadiremos toda la configuración, en este artículo nos vamos a enfocar en sacar los tipados de nuestro endpoint, ya que la herramienta puede generar hasta las peticiones y los DTO del lenguaje, desde Typescript, a Angular, pasando por Jquery y C#

Voy a ponerte un archivo base que llamaremos config.nswag:

{
  "runtime": "Net80",
  "defaultVariables": null,
  "documentGenerator": {
    "fromDocument": {
      "url": "[la dirección del swagger.json de tu endpoint]",
      "output": null,
      "newLineBehavior": "Auto"
    }
  },
  "codeGenerators": {
    "openApiToTypeScriptClient": {
      "className": "{controller}Client",
      "moduleName": "",
      "namespace": "",
      "typeScriptVersion": 5.4,
      "template": "Fetch",
      "promiseType": "Promise",
      "httpClass": "HttpClient",
      "withCredentials": false,
      "useSingletonProvider": false,
      "injectionTokenType": "OpaqueToken",
      "dateTimeType": "Date",
      "nullValue": "Undefined",
      "generateClientClasses": false,
      "generateClientInterfaces": true,
      "generateOptionalParameters": false,
      "exportTypes": true,
      "wrapDtoExceptions": false,
      "exceptionClass": "SwaggerException",
      "clientBaseClass": null,
      "wrapResponses": false,
      "generateResponseClasses": true,
      "responseClass": "SwaggerResponse",
      "configurationClass": null,
      "useTransformOptionsMethod": false,
      "useTransformResultMethod": false,
      "generateDtoTypes": true,
      "operationGenerationMode": "MultipleClientsFromOperationId",
      "markOptionalProperties": true,
      "generateCloneMethod": false,
      "typeStyle": "Interface",
      "enumStyle": "Enum",
      "useLeafType": false,
      "extensionCode": null,
      "generateDefaultValues": true,
      "handleReferences": false,
      "generateTypeCheckFunctions": false,
      "generateConstructorInterface": true,
      "convertConstructorInterfaceData": false,
      "importRequiredTypes": true,
      "useGetBaseUrlMethod": false,
      "baseUrlTokenName": "API_BASE_URL",
      "useAbortSignal": false,
      "inlineNamedDictionaries": false,
      "inlineNamedAny": false,
      "includeHttpContext": false,
      "templateDirectory": null,
      "serviceHost": null,
      "serviceSchemes": null,
      "output": "src/app/api/interfaces.ts",
      "newLineBehavior": "Auto"
    }
  }
}

Asegúrate de cambiar la url del from document, tanto local cómo externa
y de cambiar el output de codeGenerators a la ruta que prefieras para guardar los typos de tu endpoint.

Generar Interfaces

Una vez tenemos el archivo de configuración podemos ejecutar nswag con el comando

npx nswag run ./config.nswag

Ahora podemos ir a la ruta de nuestro output y ver todos los tipos y enums de nuestro endpoint en nuestro caso sería src/app/api/interfaces.ts

Final

Pero esta herramienta no se queda aquí, puedes generar los DTOs, las peticiones y hasta los servicios de tu endpoint, todo de manera automática y en pocos segundos.

Si quieres saber más sobre esta herramienta, te recomiendo que visites la documentación oficial de NSwag.

¡Espero que te haya sido de ayuda! Si tienes alguna duda, no dudes en preguntar en los comentarios.

Y no te olvides de seguirme en redes sociales para estar al tanto de todas las novedades.

Redes

Twitter
Twitch
Instagram
Github
Otras redes