Strict Swagger Documentation for Auth Module

[Villarley]

🚀 Issue: Strict Swagger Documentation for Auth Module

📋 Description

Begin improving and enforcing strict Swagger documentation for the API by starting with the auth module. Every route, payload, parameter, and response must be documented thoroughly and accurately following OpenAPI 3.0+ standards. This task will act as a base for future documentation of all other modules.

---

🎯 Objectives

• Document all auth endpoints located in both /api/v1/auth/ and /auth/ (if legacy)
• Define all request and response schemas in the OpenAPI spec (openapi.yaml)
• Add precise descriptions, examples, and status code documentation
• Ensure consistency with existing DTOs and TypeScript types
• Align field descriptions with domain vocabulary (wallet, roles, token, etc.)

---

📁 Files to edit

/openapi.yaml                       // Centralized OpenAPI spec file
/src/modules/auth/dto/             // Ensure matching with DTOs
/src/modules/auth/presentation/   // Controller methods to document

---

📌 Endpoints to Document (Auth)

POST /api/v1/auth/register

• Summary: Register a new user

• Request Body:

  • walletAddress: string, required
  • role: enum('buyer' | 'seller'), required
  • name: string, required
  • email: string, required

• Response:

  • 200: success message, user object
  • 400: validation error

POST /api/v1/auth/login

• Summary: Log in with wallet address

• Request Body:

  • walletAddress: string, required

• Response:

  • 200: JWT token
  • 401: unauthorized

POST /api/v1/auth/verify-email

• Summary: Verify email using token

• Request Param:

  • token: string

• Response:

  • 200: verification success
  • 400: invalid or expired token

POST /api/v1/auth/resend-verification

• Summary: Resend verification email

• Request Body:

  • email: string, required

• Response:

  • 200: resend confirmation
  • 404: user not found

GET /api/v1/auth/verification-status

• Summary: Check if current user’s email is verified

• Auth: Requires Bearer token

• Response:

  • 200: boolean verified flag
  • 401: not authenticated

POST /api/v1/auth/verify-wallet

• Summary: Fully verify a Stellar wallet address

• Request Body:

  • walletAddress: string

• Response:

  • 200: wallet metadata
  • 400: invalid format or unregistered

POST /api/v1/auth/validate-wallet-format

• Summary: Validate wallet address format only

• Request Body:

  • walletAddress: string

• Response:

  • 200: valid/invalid format

---

🧪 Acceptance Criteria

• All auth routes are fully documented in openapi.yaml
• Each request and response includes schema, examples, and status codes
• Required/optional fields are clearly marked
• Descriptions align with the system’s domain model
• No undocumented or partially documented auth routes remain

---

🔗 References

• [OpenAPI 3.0 Specification](https://swagger.io/specification/)
• src/modules/auth/dto/*.ts for structure alignment
• openapi.yaml file at root of project

---

⚠️ Notes

• Use YAML anchors if needed to avoid duplication of schemas
• Use components.schemas to define all payloads clearly
• This task must be completed before moving on to documenting other modules (project, user, volunteer, etc.)

---

📘 Example Schema Block (in openapi.yaml)

components:
  schemas:
    RegisterRequest:
      type: object
      required:
        - walletAddress
        - name
        - email
        - role
      properties:
        walletAddress:
          type: string
          example: "GCKFBEI..."
        role:
          type: string
          enum: [buyer, seller]
          example: "buyer"
        name:
          type: string
          example: "John Doe"
        email:
          type: string
          example: "john@example.com"

[Josue19-08]

Hi, I’m Josué. I’ve worked with OpenAPI 3.0 and Swagger documentation in TypeScript-based backends, and I understand how important accurate and strict API docs are for consistency, onboarding, and integration.

I can take full ownership of documenting the entire auth module, aligning the spec with the existing DTOs and domain language. I’ll make sure all endpoints, payloads, parameters, and responses are cleanly defined, well-described, and fully consistent with the system’s vocabulary and structure. I’ll also organize the spec for future extension and make use of schema reuse to avoid duplication.

[pushkarm029]

Hey, I can complete this quickly @Villarley

Recommended by OnlyDust for exceptional experience, quality, and reliability.

[Jafet2do]

Hola, soy Jafet Hernández, estudiante de ATI, quiero trabajar y colaborar en este Issue.