Add OpenAPI 3.0 specification for all API endpoints

[prodbycorne]

Overview

There is no formal API contract. Integrators must read source code to understand request/response shapes, error codes, and authentication. An OpenAPI 3.0 spec enables auto-generated client SDKs, Postman collections, and interactive docs.

Endpoints to Document

• GET /health
• GET /api/v1/prices/:assetCode with optional ?issuer= query param
• POST /api/v1/prices/batch
• POST /api/v1/webhooks
• GET /api/v1/webhooks
• DELETE /api/v1/webhooks/:id
• POST /api/v1/webhooks/:id/test
• GET /api/v1/indexer/status
• WS /ws (described as an AsyncAPI or OpenAPI extension)

Deliverables

1. openapi.yaml at repo root — OpenAPI 3.0.3 format
2. Serve the spec at GET /api-docs/openapi.yaml
3. Serve Swagger UI at GET /api-docs using swagger-ui-express

npm install swagger-ui-express yamljs

Schema Requirements

• All request bodies have Zod-equivalent JSON Schema definitions
• All error responses documented: 400, 401, 404, 422, 429, 500
• Authentication documented: Bearer scheme in securitySchemes
• x-rate-limit extension on rate-limited endpoints
• Examples provided for every endpoint

Acceptance Criteria

• openapi.yaml at repo root with all endpoints
• Spec validates with @redocly/cli lint openapi.yaml
• Swagger UI reachable at /api-docs in development
• All error shapes documented
• Authentication scheme included
• CI step: lint the spec on every PR

[josealfredo79]

Motivation

I would love to tackle this issue and standardize the API contract for smartdrop-backend. Having a production-ready OpenAPI 3.0 specification is crucial for developer experience, seamless integration, and reliable client SDK generation. I am highly motivated to implement a robust Swagger UI setup and ensure the specification passes rigorous linting checks via CI, preventing future drift between the codebase and the documentation.

Experience

I have extensive experience designing, documenting, and validating REST APIs using OpenAPI/Swagger and integration tools in Node.js ecosystems:

• API Documentation & Tooling: Proficient in writing modular, highly descriptive openapi.yaml specifications matching complex backend architectures. Experienced in setting up swagger-ui-express and yamljs to serve interactive docs directly from the application.
• Schema Validation & Zod: Skilled in mapping runtime Zod validation schemas directly into JSON Schema structures for OpenAPI models, ensuring that error responses (400, 422, etc.) exactly match application realities.
• CI/CD Integration: Experienced in configuring @redocly/cli to catch validation errors and enforcing API spec compliance automatically during the GitHub Actions PR workflow.

Proposed Implementation Plan

1. Setup & Dependencies: Install swagger-ui-express and yamljs as required.
2. OpenAPI 3.0.3 Definition: Author the openapi.yaml at the root including:
   • Security schemes (BearerAuth).
   • Global and route-specific error schemas (400, 401, 404, 422, 429, 500).
   • All REST endpoints (/health, /prices, /webhooks, /indexer/status) with strict JSON schema definitions, explicit types, descriptions, and mock examples.
   • Custom extensions like x-rate-limit for rate-limited routes and descriptive documentation for the WebSocket endpoint (/ws).
3. Interactive UI Hosting: Expose the specification file at /api-docs/openapi.yaml and mount the interactive Swagger UI dashboard at /api-docs (active in development mode).
4. Validation & CI: Run @redocly/cli lint openapi.yaml locally to guarantee zero errors and create the GitHub Action step to automate this verification on every PR.

[MikRoyce]

Motivation
I would love to take on this issue and establish a robust, standardized API contract for smartdrop-backend. Transitioning from source-code dependency to a formal OpenAPI 3.0 specification is a massive win for developer experience and will make generating client SDKs or Postman collections seamless. I am committed to delivering a clean, production-ready setup with an interactive Swagger UI dashboard and integrating strict linting checks into the CI workflow to prevent any future documentation drift.
Experience
I have strong hands-on experience designing, documenting, and validating RESTful ecosystems in Node.js:
OpenAPI & Swagger Tooling: Proficient in writing structured, modular openapi.yaml specs and serving them interactively using swagger-ui-express and yamljs.
Schema & Data Validation: Skilled at mapping backend runtime schemas (like Zod) into accurate JSON Schema models to ensure error payloads (400, 422, etc.) identically match actual API behavior.
CI/CD Automation: Experienced with @redocly/cli for automated linting to enforce spec compliance and catch breaking changes on every pull request.
Proposed Implementation Plan

1. Dependencies Setup: Install swagger-ui-express and yamljs.
2. Spec Authoring (openapi.yaml):
   Document all specified REST endpoints (/health, /prices, /webhooks, /indexer/status), standardizing error codes (400, 401, 404, 422, 429, 500) and adding explicit JSON schemas with examples.
   Incororporate custom x-rate-limit extensions for rate-limited routes and add clarity for the /ws WebSocket endpoint.
3. UI Exposure: Serve the raw YAML spec at /api-docs/openapi.yaml and mount the interactive Swagger UI dashboard at /api-docs (restricted to development mode).
4. Linting & CI Workflow: Run @redocly/cli lint locally to resolve any specification errors and add a dedicated GitHub Actions step to validate the spec automatically on every PR.

[grantfox-oss]

🦊 GrantFox — @josealfredo79 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 #26)
2. Your PR will be reviewed by the SmartDropLabs maintainers

Good luck! Track your progress on GrantFox.