[Documentation] Generate OpenAPI/Swagger Documentation for All API Endpoints

[KarenZita01]

Description

The EquipChain API currently has no formal API documentation, making it difficult for internal developers and potential external integrators to understand available endpoints, request formats, and response structures. This issue implements automated OpenAPI 3.1 (Swagger) documentation generation using swagger-jsdoc and swagger-ui-express to create a living documentation portal that stays synchronized with the codebase.

The documentation should cover all existing and planned API endpoints with detailed information including: path parameters, query parameters, request body schemas (referencing Zod schemas), response schemas for success and error cases, authentication requirements (indicating which endpoints require JWT), rate limit information, and example requests/responses. The Swagger UI should be served at /api-docs and protected behind authentication in production environments.

The documentation must be generated from JSDoc-style annotations in route files using swagger-jsdoc. Each route file should include a YAML or JSON comment block describing the endpoint. This approach keeps documentation close to the implementation, making it more likely to stay up-to-date. The generated OpenAPI specification should also be exportable as a JSON file (/api-docs.json) for use with API client generators like openapi-generator.

Technical Context & Impact

• Dependencies: swagger-jsdoc (^7.x), swagger-ui-express (^5.x). These are production dependencies since the docs should be served by the running API.
• Architecture: New src/config/swagger.js initializes the swagger-jsdoc instance with the API info and path to route files. New src/routes/docs.js mounts swagger-ui-express and the raw JSON endpoint.
• Impact: Good API documentation is essential for developer adoption, both internally and for external integrators who may use the webhook system (Issue [Documentation] Generate OpenAPI/Swagger Documentation for All API Endpoints #14) or API keys (Issue [Testing] Add Load Testing with k6 to Identify Performance Bottlenecks Under Stress #20). It reduces support burden and onboarding time.

Step-by-Step Implementation Guide

1. Install Dependencies: Run npm install swagger-jsdoc swagger-ui-express. These will serve the documentation from within the Express app.
2. Create Swagger Configuration: Write src/config/swagger.js that defines the OpenAPI object: version, title ("EquipChain API"), description, contact info, servers (development/production URLs), components (securitySchemes for JWT and API Key), and tags for grouping endpoints (Auth, Admin, Meters, System, Webhooks).
3. Add JSDoc Annotations to Routes: Add OpenAPI YAML comments above each route handler in src/routes/. Start with existing routes (GET /) and then add annotations for routes created in other issues (auth, admin, etc.). Each annotation should specify: summary, description, tags, parameters, requestBody (with content type), responses (with schemas).
4. Create Docs Route: Write src/routes/docs.js with GET /api-docs serving swagger-ui-express (use serve, setup), and GET /api-docs.json serving the raw OpenAPI spec object. In production, protect /api-docs behind authentication.
5. Wire in index.js: Mount the docs route in src/index.js. Ensure the docs are available at /api-docs and verify the Swagger UI renders correctly with all endpoints listed.
6. Write Validation Test: Create a test that validates the generated OpenAPI spec is valid (using swagger-parser or similar) and that all documented endpoints exist in the Express router.

Verification & Testing Steps

1. Start the server and navigate to http://localhost:3000/api-docs in a browser — verify the Swagger UI loads with the EquipChain API title and lists all documented endpoints.
2. Click on an endpoint to expand it — verify path parameters, query parameters, request body schemas, and response schemas are displayed correctly.
3. Use the "Try it out" feature — execute a request from Swagger UI and verify the response matches the documented schema.
4. Fetch http://localhost:3000/api-docs.json — verify the JSON is valid OpenAPI 3.1 spec. Use an online validator or the swagger-parser CLI to validate.
5. Temporarily set NODE_ENV=production and verify that /api-docs requires authentication (returns 401/403 without a valid JWT).

[Times-stack]

Hi! I'd like to work on this issue.

I have experience building and documenting Node.js/Express APIs, including OpenAPI/Swagger integration, schema-driven validation, and automated testing. I understand the value of keeping API documentation close to the implementation so it remains accurate as the codebase evolves.

For this task, I'll implement a complete OpenAPI 3.1 solution using "swagger-jsdoc" and "swagger-ui-express", documenting all existing endpoints with request/response schemas, authentication requirements, parameters, and examples. I'll expose both the interactive Swagger UI ("/api-docs") and the raw OpenAPI JSON ("/api-docs.json"), ensure the documentation is protected in production as specified, and add validation tests to verify the generated specification and route coverage.

I'll keep the implementation well organised, follow the project's conventions, add clear documentation where needed, and ensure all linting, tests, and builds pass before submitting a clean, reviewer-friendly PR.

I'd appreciate being assigned this issue. Thank you!

[grantfox-oss]

🦊 GrantFox — @Times-stack 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 #14)
2. Your PR will be reviewed by the EquipChain maintainers

Good luck! Track your progress on GrantFox.