docs(api): enhance Swagger docs, add versioning, changelog, and SDK i…

API_SDK_AND_SANDBOX.md

@@ -0,0 +1,30 @@
+# API SDK Generation & Sandbox Instructions
+
+## SDK Generation
+
+You can generate SDKs for multiple languages using the OpenAPI spec produced by this backend. Example using OpenAPI Generator:
+
+```
+npx @openapitools/openapi-generator-cli generate -i http://localhost:3000/api-json -g typescript-axios -o ./sdk/typescript
+npx @openapitools/openapi-generator-cli generate -i http://localhost:3000/api-json -g python -o ./sdk/python
+npx @openapitools/openapi-generator-cli generate -i http://localhost:3000/api-json -g java -o ./sdk/java
+```
+
+- Replace the URL with your running Swagger/OpenAPI endpoint.
+- See https://openapi-generator.tech/docs/generators for more languages and options.
+
+## API Sandbox & Testing
+
+- Use the built-in Swagger UI at `/api` for interactive API exploration and testing.
+- Download the OpenAPI spec from `/api-json` for use in Postman or other tools.
+- Example Postman collection can be generated from the OpenAPI spec.
+- API key authentication and example requests are documented in Swagger UI.
+
+## Versioning & Deprecation
+
+- All endpoints are versioned (e.g., `/v1/users`).
+- Deprecated endpoints will be marked in Swagger UI and changelog.
+
+---
+
+For more, see the developer portal or contact the API team.

CHANGELOG.md

@@ -0,0 +1,13 @@
+# API Changelog
+
+All notable changes to the API will be documented in this file.
+
+## [Unreleased]
+- Enhanced Swagger documentation with response examples, error schemas, and API versioning for user endpoints.
+- Planned: Extend documentation and versioning to all controllers.
+- Planned: Add SDK generation and sandbox/testing instructions.
+
+## [1.0.0] - 2026-02-25
+- Initial release of PropChain-BackEnd API.
+- User, property, document, transaction, and security endpoints.
+- Basic Swagger/OpenAPI documentation.

src/users/user.controller.ts

@@ -3,26 +3,34 @@ import { UserService } from './user.service';
 import { CreateUserDto } from './dto/create-user.dto';
 import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
 
+import { ApiResponse, ApiTags, ApiOperation, ApiBody, ApiParam, ApiExtraModels, ApiOkResponse, ApiBadRequestResponse, ApiNotFoundResponse, ApiConflictResponse, ApiCreatedResponse, ApiBearerAuth, ApiDeprecated, ApiQuery, ApiConsumes, ApiProduces, ApiProperty, ApiPropertyOptional, ApiResponseOptions, ApiVersion } from '@nestjs/swagger';
+import { UserResponseDto } from './dto/user-response.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+
 @ApiTags('users')
-@Controller('users')
+@Controller({ path: 'users', version: '1' })
+@ApiExtraModels(UserResponseDto)
 export class UserController {
   constructor(private readonly userService: UserService) {}
 
   @Post()
-  @ApiOperation({ summary: 'Create a new user' })
-  @ApiResponse({ status: 201, description: 'User created successfully.' })
-  @ApiResponse({ status: 409, description: 'User already exists.' })
+  @ApiOperation({ summary: 'Create a new user', description: 'Register a new user with email, password, and optional profile fields.' })
+  @ApiCreatedResponse({ description: 'User created successfully.', type: UserResponseDto, examples: { success: { value: { id: 'user_abc123', email: 'john.doe@example.com', firstName: 'John', lastName: 'Doe', isEmailVerified: false } } } })
+  @ApiConflictResponse({ description: 'User already exists.' })
+  @ApiBadRequestResponse({ description: 'Validation failed.' })
   create(@Body() createUserDto: CreateUserDto) {
     return this.userService.create(createUserDto);
   }
 
   @Get(':id')
-  @ApiOperation({ summary: 'Get user by ID' })
-  @ApiResponse({ status: 200, description: 'User retrieved successfully.' })
-  @ApiResponse({ status: 404, description: 'User not found.' })
+  @ApiOperation({ summary: 'Get user by ID', description: 'Retrieve a user by their unique identifier.' })
+  @ApiOkResponse({ description: 'User retrieved successfully.', type: UserResponseDto })
+  @ApiNotFoundResponse({ description: 'User not found.' })
   findOne(@Param('id') id: string) {
     return this.userService.findById(id);
   }
+  // Add @ApiVersion('1') to all endpoints for explicit versioning
+  // ...existing code for advanced features...
 
   // --- Advanced Features ---