Add OpenAPI (Swagger) generation, API Explorer and generated TypeScript client

[memplethee-lab]

Summary

What: Add automated OpenAPI (Swagger) generation with an API explorer and generated TypeScript client.
Why: Improves developer onboarding, enables third-party integrations, ensures up-to-date API docs, and reduces integration friction.
Which part: API surface, controller decorators, build pipeline, and docs site.

Problem Statement

Current limitation

• The repository lacks a single canonical, easily browsable, and machine-readable OpenAPI specification and an in-repo API explorer.
• Consumers and integrators must read README and source code to understand endpoints, request/response shapes.

Pain point

• Slows third-party integrations and SDK generation; increases onboarding friction for contributors and integrators.

Why it matters

• An up-to-date OpenAPI spec enables automatic client generation, API validation, and better documentation for maintainers and integrators.

Proposed Solution

How it should work

• Add automatic OpenAPI (Swagger) generation using NestJS Swagger module during runtime and CI builds.
• Generate and publish a static OpenAPI JSON/YAML artifact to docs/ or GitHub Pages on each CI release.
• Add a lightweight API explorer (Swagger UI or Redoc) hosted under /docs or /api-explorer when running the server in development.
• Add a codegen step (OpenAPI Generator or @openapitools/openapi-generator-cli) for producing a TypeScript client bundle in /client or as an npm artifact.

Expected behavior

• Running the app in dev exposes /api-explorer with interactive docs.
• CI artifacts include openapi.json and an optional generated client tarball.

Important notes

• Keep Swagger generation opt-in in production (env guard) to avoid leaking internal schemas.

Implementation Guidance

Files/folders likely affected

• src/main.ts (enable Swagger setup under dev env)
• package.json (add codegen scripts)
• docs/ (store generated artifacts)
• .github/workflows/ci.yml (add generation and upload steps)

Modules/Services involved

• App bootstrap (SwaggerModule)
• DTOs and controllers (ensure decorators and ApiProperty usage)

Dependencies/prerequisites

• @nestjs/swagger, swagger-ui-express or redoc, @openapitools/openapi-generator-cli
• Node and CI runner (already present)

Suggested steps

1. Add @nestjs/swagger and configure in src/main.ts guarded by NODE_ENV !== 'production'.
2. Annotate public DTOs with ApiProperty where missing.
3. Add npm scripts: "generate:openapi", "generate:client".
4. Add CI job to run generation and publish artifacts to docs/ (or release assets).
5. Add README section documenting usage and client generation.

Acceptance Criteria

Acceptance Criteria

• Swagger UI available in development at /api-explorer
• openapi.json and openapi.yaml generated by CI and stored in docs/
• TypeScript client generation script exists and produces a usable client
• DTOs annotated so generated spec reflects request/response shapes
• Documentation updated (README + docs/) with usage instructions
• Unit/integration tests added where appropriate
• Feature passes linting and existing CI checks

Technical Notes

API changes

• No breaking API changes; only metadata and docs added.
  Database changes
• None.
  Security
• Ensure Swagger UI disabled in production by default; require env var to enable.
  Performance
• Generation runs only during build/CI; runtime overhead minimal when disabled.
  Accessibility
• Ensure generated docs are reachable and documented for keyboard navigation.
  Edge cases
• Some complex DTO types may require manual decorators for proper schema generation.

Definition of Done

• All acceptance criteria met
• README updated with generation and explorer instructions
• CI job added and green
• Generated artifacts appear under docs/

Labels

• enhancement, feature, backend, documentation

Priority

• Medium

Estimated Difficulty

• Intermediate

Estimated Effort

• M