[backend] Swagger / OpenAPI Documentation for All Endpoints

[josueazc]

DESCRIPTION

The NestJS API has no auto-generated documentation. Contributors and frontend developers must read raw TypeScript source to discover available endpoints, required headers, request bodies, and response shapes. NestJS ships with @nestjs/swagger which generates an interactive Swagger UI and an openapi.json spec from decorators — zero separate doc-writing required.

GOAL

A Swagger UI is served at /api/docs when the API runs locally. Every endpoint shows its HTTP method, path, required auth, request body schema, and possible response codes. Developers can explore and test the API from the browser without reading source code.

REQUIREMENTS

• Install @nestjs/swagger and swagger-ui-express in apps/api
• Bootstrap the SwaggerModule in apps/api/src/main.ts with project metadata (title: VELAR API, version, description)
• Mount the UI at /api/docs (only in non-production environments)
• Add @ApiTags() to every controller: auth, bonds, transfers, audit, users, parties, reports
• Add @ApiBearerAuth() to every controller or route guarded by AuthGuard
• Decorate the main DTOs / input classes with @ApiProperty() so request body schemas appear in the UI:
  • RegisterDto (or current RegisterInput)
  • RegisterBondInput and BondRequestInput from @velar/types
• Add @ApiResponse() on at least the most important responses (200, 201, 400, 401, 403)
• Export the openapi.json spec as a static file under apps/api/public/openapi.json so it can be consumed by external tools

ACCEPTANCE CRITERIA

• GET /api/docs returns the Swagger UI when running npm run start:dev in apps/api
• All controllers appear as tagged sections in the UI
• Authenticated routes show the lock icon and require a Bearer token to be tested
• Request body schemas for /auth/register and /bonds are fully described (no {} body)
• npm run build passes in apps/api
• npm run lint without new errors
• Swagger UI is not exposed in production (NODE_ENV === 'production' guard in main.ts)

NOTES

Relevant files: apps/api/src/main.ts, apps/api/src/auth/auth.controller.ts, apps/api/src/bonds/bonds.controller.ts, apps/api/src/transfers/transfers.controller.ts, apps/api/src/audit/audit.controller.ts.
Reference: https://docs.nestjs.com/openapi/introduction

Good first task — no blockchain or Stellar knowledge required. Purely additive change with no risk of breaking existing behavior.

---

Difficulty: Beginner
Priority: Medium

[bshuaibu1]

Hi, I'd like to take this on. I work regularly with NestJS and @nestjs/swagger, so the decorator-driven approach here is familiar.

My plan:

Add @nestjs/swagger + swagger-ui-express to apps/api, bootstrap SwaggerModule in main.ts with the VELAR API title/version/description, and mount the UI at /api/docs behind a NODE_ENV !== 'production' guard.

Tag every controller (auth, bonds, transfers, audit, users, parties, reports) and add @ApiBearerAuth() to all AuthGuard-protected routes so the lock icon and Bearer auth work in the UI.

Decorate RegisterDto, RegisterBondInput, and BondRequestInput with @ApiProperty() so /auth/register and /bonds show full request schemas (no empty {} bodies), plus @apiresponse() for the key 200/201/400/401/403 cases.

Export the spec to apps/api/public/openapi.json.

I'll verify npm run start:dev serves the docs, and that npm run build and npm run lint both pass before opening the PR. It's purely additive, so no risk to existing behavior.

[Menjay7]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[jaynomyaro]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[anidroid1184]

Hi! I would like to apply for this issue to implement the automated Swagger/OpenAPI documentation for the VELAR API. This will be an excellent step for me to get involved with the project and improve the developer experience for the team!

I have reviewed the CONTRIBUTING.md guidelines and analyzed the project structure. My technical approach will be:

1. Create a dedicated branch following conventions: feat/api-swagger-docs.
2. Install @nestjs/swagger and swagger-ui-express in apps/api.
3. Bootstrap the SwaggerModule in apps/api/src/main.ts with the requested metadata (VELAR API) and wrap it inside a environment guard (NODE_ENV !== 'production') to meet your strict security standards.
4. Decorate the required controllers with @ApiTags() and @ApiBearerAuth(), and update the main DTOs using @ApiProperty() to fully describe the request bodies.
5. Export the openapi.json spec as a static file under apps/api/public/.
6. Run npm run build --workspace apps/api and npm run lint to ensure everything compiles flawlessly before submitting the PR.

I am ready to start as soon as you can assign this issue to me!

[grantfox-oss]

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

Next steps:

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

Good luck! Track your progress on GrantFox.