feat: histories api 명세 작성 (#48)

* feat: histories swagger api 구조 작성

* refactor: 🚚 histories 폴더 구조 변경

* feat: histories dto 추가

* feat: swagger 명세 작성

* refactor:

* feat: Request, Reponse용 스키마 구별

* feat:

* [autofix.ci] apply automated fixes

* Update backend/src/histories/schema/histories.schema.ts

Co-authored-by: scarf <[email protected]>

* Update backend/src/histories/dto/histories.dto.ts

Co-authored-by: scarf <[email protected]>

* feat: 결과 스키마 구체화

* feat:

* feat: zodToOpneAPI를 이용하여 조회 결과를 스키마로 작성

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: scarf <[email protected]>

backend/src/app.module.ts

@@ -2,7 +2,7 @@ import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm'; // Add this line
 import { AppController } from './app.controller';
 import { AppService } from './app.service';
-import { HistoriesModule } from './repository/module/histories.module';
+import { HistoriesModule } from './histories/histories.module';
 
 import * as dotenv from 'dotenv';
 dotenv.config();

backend/src/histories/dto/histories.dto.ts

@@ -0,0 +1,4 @@
+import { createZodDto } from '@anatine/zod-nestjs';
+import { getHistoriesRequestSchema } from '../schema/histories.schema';
+
+export class getHistoriesDto extends createZodDto(getHistoriesRequestSchema) {}

backend/src/histories/histories.controller.ts

@@ -0,0 +1,27 @@
+import { Controller, Get, Query } from '@nestjs/common';
+import { ApiOperation, ApiResponse } from '@nestjs/swagger';
+import { HistoriesService } from 'src/histories/histories.service';
+import { getHistoriesDto } from 'src/histories/dto/histories.dto'; // Adjust the import path as necessary
+import { getHistoriesResponseSchema } from './schema/histories.schema';
+import { zodToOpenAPI } from 'nestjs-zod';
+
+@Controller('histories')
+export class HistoriesController {
+  constructor(private historiesService: HistoriesService) {}
+
+  @Get()
+  @ApiOperation({
+    summary: '대출 기록 조회',
+    description:
+      '현재까지의 대출 기록을 최신순으로 가져온다. 사서라면 모든 사용자의 기록을, 사서가 아니라면 본인의 기록만 볼 수 있다.',
+    tags: ['histories'],
+  })
+  @ApiResponse({
+    status: 200,
+    description: '대출 기록을 반환한다.',
+    schema: zodToOpenAPI(getHistoriesResponseSchema),
+  })
+  getHistories(@Query() query: getHistoriesDto) {
+    return this.historiesService.getHistories();
+  }
+}

backend/src/repository/module/histories.module.ts → backend/src/histories/histories.module.ts

@@ -1,9 +1,9 @@
 import { Module } from '@nestjs/common';
-import { HistoriesService } from 'src/service/histories.service';
-import { historiesProviders } from '../providers/histories.providers'; // Import the 'historiesProviders' variable from the correct file
+import { HistoriesService } from 'src/histories/histories.service';
+import { historiesProviders } from './histories.providers'; // Import the 'historiesProviders' variable from the correct file
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { VHistories } from 'src/entities/VHistories';
-import { HistoriesController } from 'src/controller/histories.controller';
+import { HistoriesController } from 'src/histories/histories.controller';
 
 @Module({
   imports: [TypeOrmModule.forFeature([VHistories])],

backend/src/histories/schema/histories.schema.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+export const getHistoriesRequestSchema = z.object({
+  who: z
+    .enum(['all', 'my'])
+    .describe(
+      '모든 사용자의 기록을 볼 것인지, 본인의 기록만 볼 것인지 결정하는 필터',
+    ),
+  query: z.string().optional().describe('검색어'),
+  type: z
+    .enum(['user', 'title', 'callsign', 'bookId'])
+    .optional()
+    .describe('어떤 값들로 검색하고 싶은지 결정하는 필터'),
+  page: z.number().optional().describe('페이지 번호'),
+  limit: z.number().optional().describe('한 페이지에 보여줄 항목 수'),
+});
+
+export const getHistoriesResponseSchema = z
+  .object({
+    items: z.array(
+      z.object({
+        id: z.number().int(),
+        lendingCondition: z.string(),
+        login: z.string(),
+        returningCondition: z.string(),
+        penaltyDays: z.number().int(),
+        callSign: z.string(),
+        title: z.string(),
+        bookInfoId: z.number().int(),
+        createdAt: z.string(),
+      }),
+    ),
+    meta: z.object({
+      totalItems: z.number().positive().describe('전체 대출 기록 수'),
+      itemCount: z.number().positive().describe('현재 페이지의 대출 기록 수'),
+      itemsPerPage: z
+        .number()
+        .positive()
+        .describe('한 페이지에 보여줄 대출 기록 수'),
+      totalPages: z.number().positive().describe('전체 페이지 수'),
+      currentPage: z.number().positive().describe('현재 페이지 번호'),
+    }),
+  })
+  .describe('대출 기록 조회 응답');