Merge pull request #591 from janhq/api-update

API: added the API reference decorator

Author: irfanpena

cortex-js/package-lock.json

@@ -9,7 +9,16 @@ import {
 } from '@nestjs/common';
 import { AssistantsUsecases } from '@/usecases/assistants/assistants.usecases';
 import { CreateAssistantDto } from '@/infrastructure/dtos/assistants/create-assistant.dto';
-import { ApiTags } from '@nestjs/swagger';
+import { DeleteAssistantResponseDto } from '@/infrastructure/dtos/assistants/delete-assistant.dto';
+import {
+  ApiCreatedResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+  ApiResponse
+} from '@nestjs/swagger';
+import { AssistantEntity } from '../entities/assistant.entity';
 import { TransformInterceptor } from '../interceptors/transform.interceptor';
 
 @ApiTags('Assistants')
@@ -18,21 +27,55 @@ import { TransformInterceptor } from '../interceptors/transform.interceptor';
 export class AssistantsController {
   constructor(private readonly assistantsService: AssistantsUsecases) {}
 
+  @ApiOperation({
+    summary: 'Create assistant',
+    description: 'Creates a new assistant.',
+  })
+  @ApiCreatedResponse({
+    description: 'The assistant has been successfully created.',
+  })
   @Post()
   create(@Body() createAssistantDto: CreateAssistantDto) {
     return this.assistantsService.create(createAssistantDto);
   }
 
+  @ApiOperation({
+    summary: 'List assistants',
+    description: 'Retrieves all the available assistants along with their settings.',
+  })
+  @ApiOkResponse({
+    description: 'Ok',
+    type: [AssistantEntity],
+  })
   @Get()
   findAll() {
     return this.assistantsService.findAll();
   }
 
+  @ApiOperation({
+    summary: 'Get assistant',
+    description: "Retrieves a specific assistant defined by an assistant's `id`.",
+  })
+  @ApiOkResponse({
+    description: 'Ok',
+    type: AssistantEntity,
+  })
+  @ApiParam({ name: 'id', required: true, description: "The unique identifier of the assistant." })
   @Get(':id')
   findOne(@Param('id') id: string) {
     return this.assistantsService.findOne(id);
   }
 
+  @ApiOperation({
+    summary: 'Delete assistant',
+    description: "Deletes a specific assistant defined by an assistant's `id`.",
+  })
+  @ApiResponse({
+    status: 200,
+    description: 'The assistant has been successfully deleted.',
+    type: DeleteAssistantResponseDto,
+  })
+  @ApiParam({ name: 'id', required: true, description: "The unique identifier of the assistant." })
   @Delete(':id')
   remove(@Param('id') id: string) {
     return this.assistantsService.remove(id);

cortex-js/src/infrastructure/controllers/assistants.controller.ts

@@ -2,7 +2,14 @@ import { Body, Controller, Post, Headers, Res, HttpCode } from '@nestjs/common';
 import { CreateChatCompletionDto } from '@/infrastructure/dtos/chat/create-chat-completion.dto';
 import { ChatUsecases } from '@/usecases/chat/chat.usecases';
 import { Response } from 'express';
-import { ApiResponse, ApiTags } from '@nestjs/swagger';
+import {
+  ApiCreatedResponse,
+  ApiExtraModels,
+  ApiOperation,
+  ApiTags,
+  getSchemaPath,
+  ApiResponse
+} from '@nestjs/swagger';
 import { ChatCompletionResponseDto } from '../dtos/chat/chat-completion-response.dto';
 
 @ApiTags('Inference')
@@ -13,7 +20,7 @@ export class ChatController {
   @HttpCode(200)
   @ApiResponse({
     status: 200,
-    description: 'Chat completion response successfully',
+    description: 'Ok',
     type: ChatCompletionResponseDto,
   })
   @Post('completions')

cortex-js/src/infrastructure/controllers/chat.controller.ts

@@ -1,5 +1,5 @@
 import { Body, Controller, HttpCode, Post } from '@nestjs/common';
-import { ApiResponse, ApiTags } from '@nestjs/swagger';
+import { ApiResponse, ApiTags, ApiOperation } from '@nestjs/swagger';
 import { StartCortexDto } from '@/infrastructure/dtos/cortex/start-cortex.dto';
 import { CortexOperationSuccessfullyDto } from '../dtos/cortex/cortex-operation-successfully.dto';
 import { CortexUsecases } from '@/usecases/cortex/cortex.usecases';
@@ -15,6 +15,10 @@ export class CortexController {
     description: 'Start Cortex successfully',
     type: CortexOperationSuccessfullyDto,
   })
+  @ApiOperation({
+    summary: 'Start cortex',
+    description: 'Starts the cortex operation.',
+  })
   @Post('start')
   startCortex(@Body() startCortexDto: StartCortexDto) {
     return this.cortexUsecases.startCortex(
@@ -29,6 +33,10 @@ export class CortexController {
     description: 'Stop Cortex successfully',
     type: CortexOperationSuccessfullyDto,
   })
+  @ApiOperation({
+    summary: 'Stop cortex',
+    description: 'Stops the cortex operation.',
+  })
   @Post('stop')
   stopCortex() {
     return this.cortexUsecases.stopCortex();

cortex-js/src/infrastructure/controllers/cortex.controller.ts

@@ -5,13 +5,24 @@ import {
   Body,
   Patch,
   Param,
+  HttpCode,
   Delete,
   UseInterceptors,
 } from '@nestjs/common';
 import { MessagesUsecases } from '@/usecases/messages/messages.usecases';
 import { CreateMessageDto } from '@/infrastructure/dtos/messages/create-message.dto';
 import { UpdateMessageDto } from '@/infrastructure/dtos/messages/update-message.dto';
-import { ApiTags } from '@nestjs/swagger';
+import { ListMessagesResponseDto } from '@/infrastructure/dtos/messages/list-message.dto';
+import { GetMessageResponseDto } from '@/infrastructure/dtos/messages/get-message.dto';
+import { DeleteMessageResponseDto } from '@/infrastructure/dtos/messages/delete-message.dto';
+import {
+  ApiCreatedResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+  ApiResponse
+} from '@nestjs/swagger';
 import { TransformInterceptor } from '../interceptors/transform.interceptor';
 
 @ApiTags('Messages')
@@ -20,26 +31,64 @@ import { TransformInterceptor } from '../interceptors/transform.interceptor';
 export class MessagesController {
   constructor(private readonly messagesUsecases: MessagesUsecases) {}
 
+  @HttpCode(201)
+  @ApiResponse({
+    status: 201,
+    description: 'The message has been successfully created.',
+    type: CreateMessageDto,
+  })
+  @ApiOperation({ summary: 'Create message', description: "Creates a message in a thread." })
   @Post()
   create(@Body() createMessageDto: CreateMessageDto) {
     return this.messagesUsecases.create(createMessageDto);
   }
 
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'Ok',
+    type: ListMessagesResponseDto,
+  })
+  @ApiOperation({ summary: 'List messages', description: "Retrieves all the messages in a thread." })
   @Get()
   findAll() {
     return this.messagesUsecases.findAll();
   }
 
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'Ok',
+    type: GetMessageResponseDto,
+  })
+  @ApiOperation({ summary: 'Retrieve message', description: "Retrieves a specific message defined by a message's `id`." })
+  @ApiParam({ name: 'id', required: true, description: "The unique identifier of the message." })
   @Get(':id')
   findOne(@Param('id') id: string) {
     return this.messagesUsecases.findOne(id);
   }
 
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'The message has been successfully updated.',
+    type: UpdateMessageDto,
+  })
+  @ApiOperation({ summary: 'Update message', description: "Updates a specific message defined by a message's `id`." })
+  @ApiParam({ name: 'id', required: true, description: "The unique identifier of the message." })
   @Patch(':id')
   update(@Param('id') id: string, @Body() updateMessageDto: UpdateMessageDto) {
     return this.messagesUsecases.update(id, updateMessageDto);
   }
 
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'Successfully deleted the message.',
+    type: DeleteMessageResponseDto,
+  })
+  @ApiOperation({ summary: 'Delete message', description: "Deletes a specific message defined by a message's `id`." })
+  @ApiParam({ name: 'id', required: true, description: "The unique identifier of the message." })
   @Delete(':id')
   remove(@Param('id') id: string) {
     return this.messagesUsecases.remove(id);

cortex-js/src/infrastructure/controllers/messages.controller.ts

@@ -12,7 +12,18 @@ import {
 import { ModelsUsecases } from '@/usecases/models/models.usecases';
 import { CreateModelDto } from '@/infrastructure/dtos/models/create-model.dto';
 import { UpdateModelDto } from '@/infrastructure/dtos/models/update-model.dto';
-import { ApiResponse, ApiTags } from '@nestjs/swagger';
+import { ModelDto } from '@/infrastructure/dtos/models/model-successfully-created.dto';
+import { ListModelsResponseDto } from '@/infrastructure/dtos/models/list-model-response.dto';
+import { DeleteModelResponseDto } from '@/infrastructure/dtos/models/delete-model.dto';
+import { DownloadModelResponseDto } from '@/infrastructure/dtos/models/download-model.dto';
+import {
+  ApiCreatedResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+  ApiResponse
+} from '@nestjs/swagger';
 import { StartModelSuccessDto } from '@/infrastructure/dtos/models/start-model-success.dto';
 import { ModelSettingParamsDto } from '../dtos/models/model-setting-params.dto';
 import { TransformInterceptor } from '../interceptors/transform.interceptor';
@@ -23,6 +34,13 @@ import { TransformInterceptor } from '../interceptors/transform.interceptor';
 export class ModelsController {
   constructor(private readonly modelsUsecases: ModelsUsecases) {}
 
+  @HttpCode(201)
+  @ApiResponse({
+    status: 201,
+    description: 'The model has been successfully created.',
+    type: StartModelSuccessDto,
+  })
+  @ApiOperation({ summary: 'Create model', description: "Creates a model `.json` instance file manually." })
   @Post()
   create(@Body() createModelDto: CreateModelDto) {
     return this.modelsUsecases.create(createModelDto);
@@ -31,9 +49,11 @@ export class ModelsController {
   @HttpCode(200)
   @ApiResponse({
     status: 200,
-    description: 'The model has been started successfully.',
+    description: 'The model has been successfully started.',
     type: StartModelSuccessDto,
   })
+  @ApiOperation({ summary: 'Start model', description: "Starts a model operation defined by a model `id`." })
+  @ApiParam({ name: 'modelId', required: true, description: "The unique identifier of the model." })
   @Post(':modelId/start')
   startModel(
     @Param('modelId') modelId: string,
@@ -45,34 +65,74 @@ export class ModelsController {
   @HttpCode(200)
   @ApiResponse({
     status: 200,
-    description: 'The model has been stopped successfully.',
+    description: 'The model has been successfully stopped.',
     type: StartModelSuccessDto,
   })
+  @ApiOperation({ summary: 'Stop model', description: "Stops a model operation defined by a model `id`." })
+  @ApiParam({ name: 'modelId', required: true, description: "The unique identifier of the model." })
   @Post(':modelId/stop')
   stopModel(@Param('modelId') modelId: string) {
     return this.modelsUsecases.stopModel(modelId);
   }
 
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'Ok',
+    type: DownloadModelResponseDto,
+  })
+  @ApiOperation({ summary: 'Download model', description: "Downloads a specific model instance." })
+  @ApiParam({ name: 'modelId', required: true, description: "The unique identifier of the model." })
   @Get('download/:modelId')
   downloadModel(@Param('modelId') modelId: string) {
     return this.modelsUsecases.downloadModel(modelId);
   }
 
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'Ok',
+    type: ListModelsResponseDto,
+  })
+  @ApiOperation({ summary: 'List models', description: "Lists the currently available models, and provides basic information about each one such as the owner and availability. [Equivalent to OpenAI's list model](https://platform.openai.com/docs/api-reference/models/list)." })
   @Get()
   findAll() {
     return this.modelsUsecases.findAll();
   }
 
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'Ok',
+    type: ModelDto,
+  })
+  @ApiOperation({ summary: 'Get model', description: "Retrieves a model instance, providing basic information about the model such as the owner and permissions. [Equivalent to OpenAI's list model](https://platform.openai.com/docs/api-reference/models/retrieve)." })
+  @ApiParam({ name: 'id', required: true, description: "The unique identifier of the model." })
   @Get(':id')
   findOne(@Param('id') id: string) {
     return this.modelsUsecases.findOne(id);
   }
 
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'The model has been successfully updated.',
+    type: UpdateModelDto,
+  })
+  @ApiOperation({ summary: 'Update model', description: "Updates a model instance defined by a model's `id`." })
+  @ApiParam({ name: 'id', required: true, description: "The unique identifier of the model." })
   @Patch(':id')
   update(@Param('id') id: string, @Body() updateModelDto: UpdateModelDto) {
     return this.modelsUsecases.update(id, updateModelDto);
   }
 
+  @ApiResponse({
+    status: 200,
+    description: 'The model has been successfully deleted.',
+    type: DeleteModelResponseDto,
+  })
+  @ApiOperation({ summary: 'Delete model', description: "Deletes a model. [Equivalent to OpenAI's delete model](https://platform.openai.com/docs/api-reference/models/delete)." })
+  @ApiParam({ name: 'id', required: true, description: "The unique identifier of the model." })
   @Delete(':id')
   remove(@Param('id') id: string) {
     return this.modelsUsecases.remove(id);