feat: response openapi schema & example

Author: DrewImm

examples/complete-example/index.ts

@@ -37,6 +37,7 @@ const server = new MyServer({
 	port: 3000,
 	maxPayloadSizeMB: 10,
 	log: customLogger,
+	swaggerEnabled: true,
 });
 
 server

examples/complete-example/users/create-user-endpoint.ts

@@ -1,6 +1,6 @@
 import { ApiRequest, ApiResponse, PostEndpoint } from '../../../src/index';
 import { usersRepo, User } from './users-repository';
-import { ObjectSanitizer, EmailValidator } from 'valsan';
+import { ObjectSanitizer, EmailValidator, IntegerValidator } from 'valsan';
 import { NameValSan } from './name-valsan';
 
 /**
@@ -11,11 +11,29 @@ import { NameValSan } from './name-valsan';
 export class CreateUserEndpoint extends PostEndpoint {
 	override path = '/';
 
+	override bodyExample = {
+		name: 'John Doe',
+		email: 'john@example.com',
+	};
+
 	override body = new ObjectSanitizer({
 		name: new NameValSan(),
 		email: new EmailValidator(),
 	});
 
+	override responseExample = {
+		id: 3,
+		name: 'John Doe',
+		email: 'john@example.com',
+		created: new Date(),
+	};
+
+	override response = new ObjectSanitizer({
+		id: new IntegerValidator(),
+		name: new NameValSan(),
+		email: new EmailValidator(),
+	});
+
 	async handle(request: ApiRequest, response: ApiResponse) {
 		const { name, email } = request.body;
 

examples/complete-example/users/get-user-endpoint.ts

@@ -1,6 +1,8 @@
 import { ApiRequest, ApiResponse, GetEndpoint } from '../../../src/index';
 import { NotFoundError } from '../../../src/error';
 import { usersRepo } from './users-repository';
+import { ObjectSanitizer, IntegerValidator, EmailValidator } from 'valsan';
+import { NameValSan } from './name-valsan';
 
 /**
  * Complete Example - Get User Endpoint
@@ -11,6 +13,19 @@ import { usersRepo } from './users-repository';
 export class GetUserEndpoint extends GetEndpoint {
 	override path = '/:id';
 
+	override responseExample = {
+		id: 1,
+		name: 'Alice',
+		email: 'alice@example.com',
+		created: new Date('2023-01-01'),
+	};
+
+	override response = new ObjectSanitizer({
+		id: new IntegerValidator(),
+		name: new NameValSan(),
+		email: new EmailValidator(),
+	});
+
 	async handle(request: ApiRequest, response: ApiResponse) {
 		const userId = parseInt(request.params['id'], 10);
 		const user = usersRepo[userId];

src/oas/oas-endpoint-component-converter.ts

@@ -22,6 +22,16 @@ export class OasEndpointComponentConverter {
 			});
 		}
 
+		const responseSanitizer = endpoint.response;
+
+		if (responseSanitizer) {
+			this.addSchema({
+				name: `${endpoint.name}Response`,
+				sanitizer: responseSanitizer,
+				example: endpoint.responseExample,
+			});
+		}
+
 		return this.schemas;
 	}
 

src/oas/oas-endpoint-converter.ts

@@ -3,6 +3,7 @@ import {
 	PathItemObject,
 	ParameterObject,
 	RequestBodyObject,
+	ResponsesObject,
 } from 'auto-oas/oas/v3.1';
 
 import { BaseApiEndpoint } from '../router';
@@ -60,9 +61,28 @@ export class OasEndpointConverter {
 		// Use statusCode for response
 		const status = endpoint.statusCode;
 
-		const responses = {
-			[status]: { description: 'Success' },
-		};
+		const responses: ResponsesObject = {};
+
+		// Generate success response with schema if available
+		const responseSanitizer = endpoint.response;
+		if (responseSanitizer && responseSanitizer.schema) {
+			responses[status] = {
+				description: 'Success',
+				content: {
+					'application/json': {
+						schema: {
+							$ref:
+								'#/components/schemas/' +
+								endpoint.getName() +
+								'Response',
+						},
+					},
+				},
+			};
+		}
+		else {
+			responses[status] = { description: 'Success' };
+		}
 
 		const errors = endpoint.getErrors();
 		for (const error in errors) {

src/router/endpoint.ts

@@ -49,6 +49,10 @@ export abstract class BaseApiEndpoint extends BaseApiRoute {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	public headersExample?: any;
 
+	public response?: ObjectSanitizer;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	public responseExample?: any;
+
 	public getErrors(): { [key: string]: HTTPError } {
 		return {
 			parse: new BadRequestError(),

src/router/endpoints/health-check-endpoint.ts

@@ -1,11 +1,29 @@
-import { ApiRequest, ApiResponse } from '../endpoint';
+import {
+	Iso8601TimestampValSan,
+	MinLengthValidator,
+	ObjectSanitizer,
+	StringToNumberValSan,
+} from 'valsan';
 import { GetEndpoint } from './get-endpoint';
 
 export class HealthCheckEndpoint extends GetEndpoint {
 	override path = '/health';
 
-	// eslint-disable-next-line @typescript-eslint/no-unused-vars
-	async handle(_request: ApiRequest, _response: ApiResponse) {
+	override responseExample = {
+		status: 'ok',
+		timestamp: new Date().toISOString(),
+		uptime: 12345,
+		environment: 'development',
+	};
+
+	override response = new ObjectSanitizer({
+		status: new MinLengthValidator(),
+		timestamp: new Iso8601TimestampValSan(),
+		uptime: new StringToNumberValSan(),
+		environment: new MinLengthValidator(),
+	});
+
+	async handle() {
 		return {
 			status: await this.getStatus(),
 			timestamp: await this.getTimestamp(),

test/spec/api/openapi-server.ts

@@ -47,6 +47,14 @@ class CreateUserEndpoint extends PostEndpoint {
 		email: 'john.doe@example.com',
 	};
 
+	override response = new ObjectSanitizer({
+		id: new LengthValidator({ minLength: 1, maxLength: 50 }),
+	});
+
+	override responseExample = {
+		id: 'abc123',
+	};
+
 	async handle(request: ApiRequest) {
 		const id = Math.random().toString(36).slice(2);
 		usersDb[id] = { id, ...request.body };
@@ -80,6 +88,16 @@ class GetUserEndpoint extends GetEndpoint {
 		'x-request-id': 'req-12345',
 	};
 
+	override responseExample = {
+		id: 'abc123',
+		name: 'John Doe',
+		email: 'john.doe@example.com',
+	};
+
+	override response = new ObjectSanitizer({
+		id: idValidator,
+	});
+
 	async handle(request: ApiRequest) {
 		const user = usersDb[request.params['id']];
 
@@ -107,6 +125,20 @@ class ListUsersEndpoint extends GetEndpoint {
 		email: emailValidator.copy({ isOptional: true }),
 	});
 
+	override response = new ObjectSanitizer({
+		limit: new RangeValidator({ min: 1, max: 100 }),
+		name: nameValidator,
+		email: emailValidator,
+	});
+
+	override responseExample = [
+		{
+			id: 'abc123',
+			name: 'John Doe',
+			email: 'john.doe@example.com',
+		},
+	];
+
 	async handle(request: ApiRequest) {
 		const users = Object.values(usersDb);