From 4cc99f3f23ccb54706a1cf1949467d882d17a2f9 Mon Sep 17 00:00:00 2001
From: yeuimu <2197651308@qq.com>
Date: Fri, 21 Aug 2026 11:44:25 +0800
Subject: [PATCH] fix(docs): describe tags as grouped array

---
 .../src/public/dto/public-query-good.dto.ts   | 13 ++------
 apps/api/src/public/public.controller.ts      | 30 ++++++++++++++++++-
 2 files changed, 31 insertions(+), 12 deletions(-)

diff --git a/apps/api/src/public/dto/public-query-good.dto.ts b/apps/api/src/public/dto/public-query-good.dto.ts
index 7eb8ef6..8c94005 100644
--- a/apps/api/src/public/dto/public-query-good.dto.ts
+++ b/apps/api/src/public/dto/public-query-good.dto.ts
@@ -1,4 +1,4 @@
-import { ApiProperty } from '@nestjs/swagger';
+import { ApiHideProperty, ApiProperty } from '@nestjs/swagger';
 import { plainToInstance, Transform, Type } from 'class-transformer';
 import {
   IsArray,
@@ -74,16 +74,7 @@ export class PublicQueryGoodDto {
   @IsNumberString()
   categoryId?: string;
 
-  @ApiProperty({
-    required: false,
-    type: [PublicTagFilterDto],
-    description:
-      '标签筛选分组。同组 tagIds 按 OR 匹配，不同数组元素按 AND 匹配。GET 请求建议将整个数组 JSON.stringify 后传入 tags',
-    example: [
-      { tagGroupId: '1', tagIds: ['11', '12'] },
-      { tagGroupId: '2', tagIds: ['25'] },
-    ],
-  })
+  @ApiHideProperty()
   @IsOptional()
   @Transform(tagFilters)
   @IsArray()
diff --git a/apps/api/src/public/public.controller.ts b/apps/api/src/public/public.controller.ts
index 9b96e50..1ba21f3 100644
--- a/apps/api/src/public/public.controller.ts
+++ b/apps/api/src/public/public.controller.ts
@@ -4,18 +4,28 @@ import {
   Param,
   Query,
 } from '@nestjs/common';
-import { ApiOkResponse, ApiOperation, ApiParam, ApiTags } from '@nestjs/swagger';
+import {
+  ApiExtraModels,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiQuery,
+  ApiTags,
+  getSchemaPath,
+} from '@nestjs/swagger';
 import { PublicService } from './public.service';
 import {
   PublicCountryQueryDto,
   PublicHomeGoodsQueryDto,
   PublicQueryGoodDto,
+  PublicTagFilterDto,
 } from './dto/public-query-good.dto';
 import { PublicTagDto } from './dto/public-tag.dto';
 import { PublicGoodDetailDto, PublicTagGroupFilterDto } from './dto/public-good-detail.dto';
 import { PublicGoodDto } from './dto/public-good.dto';
 
 @ApiTags('public')
+@ApiExtraModels(PublicTagFilterDto)
 @Controller('public')
 export class PublicController {
   constructor(private readonly service: PublicService) {}
@@ -47,6 +57,24 @@ export class PublicController {
 
   @Get('goods')
   @ApiOperation({ summary: '分页获取商品' })
+  @ApiQuery({
+    name: 'tags',
+    required: false,
+    description:
+      '标签筛选分组。参数值为 JSON 数组；同组 tagIds 按 OR 匹配，不同标签组按 AND 匹配',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'array',
+          items: { $ref: getSchemaPath(PublicTagFilterDto) },
+        },
+        example: [
+          { tagGroupId: '1', tagIds: ['11', '12'] },
+          { tagGroupId: '2', tagIds: ['25'] },
+        ],
+      },
+    },
+  })
   getGoods(@Query() query: PublicQueryGoodDto) {
     return this.service.getGoods(query);
   }