Tipar automáticamente Swagger/OpenAPI endpoints con NSwag
Tags: webdev, typescript, tutorial, spanish
Published: 2024-06-30 15:50:15

# Tipar automáticamente Swagger/OpenAPI endpoints con NSwag

- [Tipar automáticamente Swagger/OpenAPI endpoints con NSwag](#tipar-automáticamente-swaggeropenapi-endpoints-con-nswag)  
  - [¿Qué es NSwag?](#qué-es-nswag)
  - [¿Qué necesitas?](#qué-necesitas)
  - [Instalación](#instalación)
  - [Configuración](#configuración)
  - [Generar Interfaces](#generar-interfaces)
  - [Final](#final)
  - [Redes](#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.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qpcld1wyi5aslgmkcj9f.png)

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.

```bash
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:

```json
{
  "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

```bash
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](https://github.com/RicoSuter/NSwag) 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](https://twitter.com/altaskur)
[Twitch](https://www.twitch.tv/altaskur)
[Instagram](https://www.instagram.com/altaskur/)
[Github](https://www.github.com/altaskur)
[Otras redes](https://www.github.io/altaskur)