如何在NestJs生成的Swagger文档中定义HTML响应

当然可以在NestJS中定义HTML响应，同时也能在Swagger文档里明确标识返回内容为HTML，甚至添加格式说明或示例。下面分两种常见场景给出具体实现：

1. 直接返回HTML字符串 #

如果你的接口直接返回HTML字符串，只需在控制器中设置响应头的Content-Type为text/html，并通过Swagger装饰器指定响应的媒体类型：

import { Controller, Get, Res } from '@nestjs/common';
import { ApiOkResponse } from '@nestjs/swagger';
import { Response } from 'express';

@Controller('html')
export class HtmlController {
  @Get('simple')
  @ApiOkResponse({
    description: '返回简单HTML内容',
    content: {
      'text/html': {
        schema: {
          type: 'string',
          example: '<!DOCTYPE html><html><body><h1>Hello NestJS</h1></body></html>'
        }
      }
    }
  })
  getSimpleHtml(@Res() res: Response) {
    // 设置响应类型为HTML
    res.setHeader('Content-Type', 'text/html');
    // 返回HTML字符串
    res.send('<html><body><h1>Hello NestJS</h1></body></html>');
  }
}

这里通过@ApiOkResponse的content字段指定text/html类型，同时用example字段给出HTML示例，Swagger文档里就会清晰展示返回的格式。

2. 使用模板引擎渲染HTML #

如果你的HTML内容来自模板文件（比如Handlebars、EJS），先配置NestJS的模板引擎，再在控制器中渲染模板，Swagger配置和上面类似：

第一步：配置模板引擎（以Handlebars为例） #

先安装依赖：

npm install hbs @nestjs/serve-static

在app.module.ts中配置：

import { Module } from '@nestjs/common';
import { ServeStaticModule } from '@nestjs/serve-static';
import { join } from 'path';
import { HtmlController } from './html.controller';

@Module({
  imports: [
    ServeStaticModule.forRoot({
      rootPath: join(__dirname, '..', 'public'), // 静态资源目录
    }),
  ],
  controllers: [HtmlController],
})
export class AppModule {}

第二步：控制器中渲染模板并配置Swagger #

import { Controller, Get, Render } from '@nestjs/common';
import { ApiOkResponse } from '@nestjs/swagger';

@Controller('html')
export class HtmlController {
  @Get('template')
  @ApiOkResponse({
    description: '通过模板引擎渲染的HTML页面',
    content: {
      'text/html': {
        schema: {
          type: 'string',
          example: '<!DOCTYPE html><html><body><h1>Hello {{name}}</h1></body></html>'
        },
        description: '使用Handlebars模板，包含{{name}}变量'
      }
    }
  })
  @Render('index') // 对应src/views/index.hbs模板文件
  getTemplateHtml() {
    // 传递模板变量
    return { name: 'NestJS' };
  }
}

这样Swagger文档里会明确显示该接口返回HTML类型，同时通过example和description标注模板格式。

关键注意点 #

• 必须在Swagger的响应装饰器中指定content['text/html']，否则Swagger会默认按JSON处理响应
• 如果需要更详细的模板说明，可以在description字段里补充模板的变量、结构等信息

内容的提问来源于stack exchange，提问作者VPR