core: generate OpenAPI/Swagger docs for all endpoints

[EmeditWeb]

Problem

There is no OpenAPI specification or Swagger UI for the
API. Developers integrating with StepFi must read source
code to understand endpoint shapes, request/response
schemas, and auth requirements.

What To Build

1. Install @nestjs/swagger and configure SwaggerModule in
   main.ts with title "StepFi API", version from package.json,
   description, and bearer auth scheme.

2. Add @apitags, @apioperation, @apiresponse decorators to
   every endpoint across all modules:

   • Auth (nonce, verify, refresh)
   • Learners (profile CRUD)
   • Loans (create, list, approve, assess, repay, check-default)
   • Sponsors (portfolio, yield, funded-loans)
   • Vendors (register, approve, dashboard stats, API keys)
   • Admin (parameters, audit logs, protocol stats)
   • Vouching (request, list, approve, revoke)
   • Pool (stats, deposit/withdraw XDR)
   • Health (indexer status, Stellar endpoint health)
   • Indexer (status, replay)

3. Use @ApiBody, @ApiParam, @apiquery for input schemas.
   Use @ApiBearerAuth() on all protected endpoints.
   Use @ApiOkResponse, @ApiCreatedResponse, @ApiErrorResponse.

4. Generate typed DTO classes with class-validator decorators
   and expose them via @ApiProperty.

5. Add GET /docs and GET /docs-json routes:

   • /docs renders Swagger UI
   • /docs-json returns raw OpenAPI spec

6. In development: enable Swagger UI.
   In production: serve under /docs with basic auth guard
   using DOCS_USERNAME and DOCS_PASSWORD env vars, or
   disable entirely via SWAGGER_ENABLED=false.

Files To Touch

• src/main.ts
• All controller files (add decorators)
• All DTO files (add @ApiProperty)
• src/common/decorators/api-paginated.decorator.ts (new)
• src/common/dto/paginated-response.dto.ts (new)

Acceptance Criteria

• /docs renders interactive Swagger UI
• /docs-json returns valid OpenAPI 3.0 spec
• Every endpoint documented with request/response schemas
• Auth schemes documented (JWT Bearer, X-API-Key)
• All error responses documented
• Production access gated behind basic auth
• npm run build passes

Mandatory Checks Before PR

• OpenAPI spec validates without errors
• Every endpoint has at least @apioperation and @apiresponse
• PR references this issue

[Wetshakat]

Gm
My name is Ishaku Dyelshak, a Full-Stack Developer with experience in React, Next.js, React Native, Node.js, and Smart Contract development.

I would like to work on this issue and can complete it within an estimated 3 hours. I have reviewed the requirements and am confident in delivering a quality solution within the proposed timeframe.

Looking forward to your approval. Thank you.

[pixels26]

Hi Maintener, I'd generate OpenAPI/Swagger docs for all endpoints

[grantfox-oss]

🦊 GrantFox — @pixels26 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #39)
2. Your PR will be reviewed by the StepFi-app maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@pixels26's PR #43 was approved and merged by @EmeditWeb.

🏆 @pixels26: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (48 total points). Track your full progress on GrantFox.

👏 Great work, @pixels26! Keep contributing to StepFi-app.