Documentación de las API de NestJS con Swagger

Swagger es un marco gratuito de código abierto para crear documentación API interactiva y fácil de usar. Genera páginas web interactivas que le permiten probar una API con varias entradas.

Swagger admite cargas útiles JSON y XML. La documentación que genera es adecuada para que la utilicen desarrolladores y no desarrolladores.

Puede documentar sus API web de NestJS a través de Swagger usando decoradores simples, sin tener que salir de su IDE.

Paso 1: Generación de la API

Antes de comenzar, debe crear una API de demostración que Swagger generará su documentación.

Generará la API de demostración desde cero utilizando la CLI de NestJS.

En primer lugar, genere un nuevo proyecto NestJS ejecutando:

nido nuevo <nombre-de-tu-proyecto>

Luego, cambie el directorio a su proyecto ya creado ejecutando:

discos compactos <nombre-de-tu-proyecto>

A continuación, generará una API REST con la CLI ejecutando:

nido generar demostración de recursos --sin especificaciones

Verá una consulta que pregunta: "¿Qué capa de transporte usa?" Seleccione API REST.

Verá otra consulta que pregunta: "¿Le gustaría generar puntos de entrada CRUD?" Escribe Y y golpear Ingresar.

El comando anterior genera una API REST completamente funcional con puntos finales CRUD y sin los archivos de prueba de unidad. Por lo tanto, la --sin especificaciones marca en el comando anterior.

Paso 2: Instalar Swagger

Instale Swagger y su biblioteca Express UI ejecutando:

npm Instalar en pc--guardar @nestjs/swagger swagger-ui-express

Paso 3: Configurar Swagger

En tus principal.ts archivo, importar Módulo Swagger y Creador de documentos de @nestjs/arrogancia.

DocumentBuilder ayuda en la estructuración de un documento base. Proporciona varios métodos que puede encadenar y cerrar con el construir método.

Estos métodos permiten la configuración de muchos atributos, como el título, la descripción y la versión.

Crear un configuración variable de objeto en su oreja funcionar así:

constante configuración = nuevo Generador de documentos()
 .setTitle('API de demostración')
 .setDescription('Una API de demostración con funcionalidad CRUD')
 .setVersion('1.0')
 .construir();

Una nueva instancia de DocumentBuilder crea un documento base que coincide con el Especificación de API abierta. Luego puede usar esta instancia para establecer el título, la descripción y la versión a través de sus métodos apropiados.

A continuación, deberá crear un documento completo con todas las rutas HTTP definidas mediante el documento base.

Para ello, llame al crearDocumento método en SwaggerModule. createDocument acepta dos argumentos: una instancia de aplicación y un objeto de opciones de Swagger. Almacene el resultado de esta llamada en una variable para su uso posterior:

constantedocumento = SwaggerModule.createDocument (aplicación, configuración);

A continuación, llame al configuración método en SwaggerModule. El método de instalación toma tres argumentos:

1. La ruta de la interfaz de usuario de Swagger. Por convención, puede usar "api".
2. Una instancia de aplicación
3. el documento completo

Además, el método de configuración toma un objeto de opciones opcional. Ver Documentación de NestJS sobre las opciones de documentos de Swagger para aprender más al respecto.

Al igual que:

Módulo Swagger.setup('API', aplicación, documento);

Inicie su aplicación y vaya a http://localhost:/api

Debería ver la interfaz de usuario de Swagger en la página.

La imagen de arriba es la vista predeterminada de la interfaz de usuario de Swagger, con todas las rutas HTTP definidas en su controlador. Deberá personalizarlo para que se ajuste a la funcionalidad de su API.

Paso 4: personalizar las propiedades de la API

De forma predeterminada, Swagger antepone toda la sección de la ruta HTTP con un encabezado que dice "predeterminado". Puede cambiar esto anotando su clase de controlador con el @ApiTags decorador y pasando su etiqueta preferida como argumento.

Al igual que:

// demostración.controlador.ts
importar { Etiquetas API } de '@nestjs/swagger';
@ApiTags('Manifestación')
@Controlador('manifestación')
exportarclase controlador de demostración {

La sección Esquemas contiene los objetos de transferencia de datos en su API. Actualmente, la interfaz de usuario no incluye ninguna de sus propiedades.

Para declarar sus propiedades en la interfaz de usuario, simplemente agregue decoradores. Anote cada propiedad requerida con el @ApiProperty decorador. Anotar propiedades opcionales con el @ApiPropertyOpcional decorador.

Por ejemplo:

// crear-demo.dto.ts
importar { ApiProperty, ApiPropertyOpcional } de '@nestjs/swagger';
exportarclase CreateDemoDto {
@ApiProperty({
escribe: Cuerda,
 description: 'Esta es una propiedad requerida',
 })
 propiedad: cuerda;
@ApiPropertyOpcional({
escribe: Cuerda,
 description: 'Esta es una propiedad opcional',
 })
 propiedad opcional: cuerda;
}

Los decoradores @ApiProperty y @ApiPropertyOptional aceptan cada uno un objeto de opciones. Ese objeto describe la propiedad que sigue a continuación.

Tenga en cuenta que el objeto de opciones usa JavaScript, no TypeScript. De ahí las declaraciones de tipo de JavaScript (es decir, cadena, no cadena).

Al anotar las propiedades del objeto de transferencia de datos, se agrega un ejemplo de los datos esperados a la sección Esquemas. También actualiza la ruta HTTP asociada con un ejemplo de los datos esperados.

Paso 5: Establecer respuestas API

En su clase de controlador, use el @ApiRespuesta decoradores para documentar todas las posibles respuestas para cada ruta HTTP. Para cada punto final, los diferentes decoradores de @ApiResponse describen el tipo de respuestas que se esperan.

hemos explicado respuestas HTTP comunes, en caso de que no esté familiarizado con lo que significan.

Los decoradores de @ApiResponse aceptan un objeto opcional que describe la respuesta.

Respuestas POST comunes

Para una solicitud POST, las posibles respuestas incluyen:

• ApiCreatedResponseApiCreatedResponse, por 201 respuestas creadas exitosas.
• ApiUnprocessableEnityResponse, para 422 respuestas fallidas de entidades no procesables.
• ApiForbiddenResponse, por 403 respuestas prohibidas.

Por ejemplo:

// demostración.controlador.ts
@Correo()
@ApiCreatedResponse({ descripción: 'Creado con éxito' })
@ApiUnprocessableEntityResponse({ descripción: 'Solicitud incorrecta' })
@ApiForbiddenResponse({ descripción: 'Solicitud no autorizada' })
 crear(@Cuerpo() createDemoDto: CreateDemoDto) {
devolvereste.demoService.create (createDemoDto);
 }

Respuestas GET comunes

Para las solicitudes GET, las posibles respuestas incluyen:

• ApiOkRespuesta, por 200 respuestas ok.
• ApiForbiddenResponse, por 403 respuestas prohibidas.
• ApiNotFoundRespuesta, para 404 respuestas no encontradas.

Por ejemplo:

// demostración.controlador.ts
@Obtener()
@ApiOkRespuesta({ descripción: 'Los recursos se devolvieron correctamente' })
@ApiForbiddenResponse({ descripción: 'Solicitud no autorizada' })
 encuentra todos() {
devolvereste.demoService.findAll();
 }
@Obtener(':identificación')
@ApiOkRespuesta({ descripción: 'El recurso se devolvió correctamente' })
@ApiForbiddenResponse({ descripción: 'Solicitud no autorizada' })
@ApiNotFoundRespuesta({ descripción: 'Recurso no encontrado' })
 Encuentra uno(@Param('yo hice: cuerda) {
devolvereste.demoService.findOne(+id);
 }

Respuestas comunes de PARCHE y ACTUALIZACIÓN

Para las solicitudes de PARCHE y ACTUALIZACIÓN, las posibles respuestas incluyen:

• ApiOkRespuesta, por 200 respuestas ok.
• ApiNotFoundRespuesta, para 404 respuestas no encontradas.
• ApiUnprocessibleEntityResponse, para 422 respuestas fallidas de entidades no procesables.
• ApiForbiddenResponse, por 403 respuestas prohibidas.

Por ejemplo:

// demostración.controlador.ts
@Parche(':identificación')
@ApiOkRespuesta({ descripción: 'El recurso se actualizó correctamente' })
@ApiNotFoundRespuesta({ descripción: 'Recurso no encontrado' })
@ApiForbiddenResponse({ descripción: 'Solicitud no autorizada' })
@ApiUnprocessableEntityResponse({ descripción: 'Solicitud incorrecta' })
 actualizar(@Param('yo hice: cuerda, @Cuerpo() actualizarDemoDto: ActualizarDemoDto) {
devolvereste.demoService.update(+id, actualizarDemoDto);
 }

Respuestas comunes de DELETE

Para las solicitudes DELETE, las posibles respuestas incluyen:

• ApiOkRespuesta, por 200 respuestas ok.
• ApiForbiddenResponse, por 403 respuestas prohibidas.
• ApiNotFoundRespuesta, para 404 respuestas no encontradas.

Por ejemplo:

// demostración.controlador.ts
@Borrar(':identificación')
@ApiOkRespuesta({ descripción: 'El recurso se devolvió correctamente' })
@ApiForbiddenResponse({ descripción: 'Solicitud no autorizada' })
@ApiNotFoundRespuesta({ descripción: 'Recurso no encontrado' })
 retirar(@Param('yo hice: cuerda) {
devolvereste.demoService.remove(+id);
 }

Estos decoradores completan su documentación con posibles respuestas. Puede verlos usando el menú desplegable junto a cada ruta.

Ver su documentación

Cuando la configuración esté completa, puede ver la documentación en servidor local:/api. Debería mostrar la documentación de la API interactiva.

Los elementos esenciales de la documentación de la API de Swagger son la descripción, los tipos de respuesta y la definición del esquema. Estas son las cosas básicas necesarias para crear una buena documentación de API.