Add API Documentation for Stellar Wallet Service [wallet - service]

[salazarsebas]

🔑 Add API Documentation for Stellar Wallet Service 🛠️

📝 Description

Create comprehensive API documentation for all endpoints in the Stellar wallet service using Swagger/OpenAPI. The documentation will cover all existing routes (e.g., authentication, KYC, wallet operations) to provide clear guidance for developers and users, ensuring easy integration and understanding of the API’s functionality.

🎯 Objective

Generate an OpenAPI specification in services/stellar-wallet/docs/api.yaml and integrate Swagger UI to serve interactive documentation at /docs, with a unit test to verify accessibility.

🗂 Structure

• Directory: services/stellar-wallet
• Files:
  • docs/api.yaml
  • src/routes/docs.js
  • tests/routes/docs.test.js
  • package.json (updated)
• Expected structure:

  services/stellar-wallet
  ├── src
  │   ├── index.js
  │   ├── stellar
  │   │   ├── client.js
  │   │   ├── keys.js
  │   │   ├── fund.js
  │   │   └── sign.js
  │   ├── db
  │   │   └── kyc.js
  │   ├── routes
  │   │   ├── kyc.js
  │   │   ├── kyc-verify.js
  │   │   ├── kyc-status.js
  │   │   ├── auth-register.js
  │   │   ├── auth-verify.js
  │   │   ├── auth-login.js
  │   │   ├── wallet.js
  │   │   └── docs.js
  │   ├── kyc
  │   │   └── validate.js
  │   ├── soroban
  │   │   ├── client.js
  │   │   ├── kyc-contract.rs
  │   │   └── deploy.js
  │   ├── auth
  │   │   ├── webauthn.js
  │   │   └── jwt.js
  │   └── middleware
  │       └── rate-limit.js
  ├── config
  │   └── db.sqlite
  ├── docs
  │   └── api.yaml
  ├── tests
  │   ├── stellar
  │   │   ├── client.test.js
  │   │   ├── keys.test.js
  │   │   ├── fund.test.js
  │   │   └── sign.test.js
  │   ├── db
  │   │   └── kyc.test.js
  │   ├── routes
  │   │   ├── kyc.test.js
  │   │   ├── kyc-verify.test.js
  │   │   ├── kyc-status.test.js
  │   │   ├── auth-register.test.js
  │   │   ├── auth-verify.test.js
  │   │   ├── auth-login.test.js
  │   │   ├── wallet.test.js
  │   │   └── docs.test.js
  │   ├── kyc
  │   │   └── validate.test.js
  │   ├── soroban
  │   │   ├── client.test.js
  │   │   └── deploy.test.js
  │   ├── auth
  │   │   └── jwt.test.js
  │   └── middleware
  │       └── rate-limit.test.js
  ├── package.json
  ├── .env.example
  ├── .eslintrc.json
  ├── .eslintignore
  ├── .prettierrc.json
  ├── .prettierignore
  ├── .gitignore
  

✅ Requirements

• Create a branch named feat/api-documentation for this task.
• Install Swagger dependencies using npm install swagger-ui-express yamljs.
• Update package.json to include swagger-ui-express and yamljs as dependencies.
• Create docs/api.yaml to define an OpenAPI 3.0 specification for all API endpoints, including:
  • /auth/register (POST, Issue 17)
  • /auth/verify (POST, Issue 18)
  • /auth/login (POST, Issue 20)
  • /kyc/submit (POST, Issue 9)
  • /kyc/verify (POST, Issue 14)
  • /kyc/status/:id (GET, Issue 15)
  • /wallet/create (POST, Issue 19)
  • /wallet/send (POST, Issue 23)
  • /wallet/transactions/:user_id (GET, Issue 24)
• Include in api.yaml:
  • Endpoint paths, methods, request/response schemas, and HTTP status codes.
  • Security schemes for JWT authentication (Bearer token) for protected endpoints.
  • Descriptions, parameters, and example responses for each endpoint.
• Create src/routes/docs.js to serve Swagger UI at /docs using swagger-ui-express, loading the api.yaml specification.
• Update src/index.js to mount the documentation route at /docs without JWT or rate-limiting middleware.
• Create a unit test in tests/routes/docs.test.js to verify that the /docs endpoint returns HTTP 200 and serves the Swagger UI.
• Mock the Express app in the unit test to avoid external dependencies.
• Ensure the code adheres to ESLint and Prettier rules (from Issue 3).
• Commit changes to the feat/api-documentation branch with a message like feat: add api documentation.
• Verify that the CI pipeline (from Issue 1) passes, with linting and test jobs succeeding.

🏆 Expected Outcomes

• swagger-ui-express and yamljs are installed and listed in package.json.
• docs/api.yaml contains a complete OpenAPI 3.0 specification for all API endpoints.
• src/routes/docs.js serves Swagger UI at /docs, displaying interactive documentation.
• /docs endpoint is accessible without authentication or rate limiting.
• Unit test in tests/routes/docs.test.js confirms the /docs endpoint returns HTTP 200.
• Code passes ESLint and Prettier checks.
• Changes are committed to the feat/api-documentation branch with a descriptive lowercase commit message.
• CI pipeline runs successfully, with linting passing for src/routes/docs.js and tests/routes/docs.test.js, and the unit test passing.

🔗 References

• Swagger UI Express
• OpenAPI 3.0 Specification
• YAML.js
• Jest Mocking
• ESLint Node.js Rules

📋 Notes

• The OpenAPI specification should include detailed schemas for request bodies (e.g., JSON payloads for /kyc/submit) and responses.
• Use examples in api.yaml to illustrate typical inputs and outputs.
• The /docs endpoint should be publicly accessible to facilitate developer onboarding.
• Mocking the Express app in tests ensures reliable CI execution.
• Commit messages must be in lowercase and start with feat, change, fix, chore, or refactor.
• The CI pipeline should validate the new code, ensuring ESLint passes and the unit test executes successfully.

[akintewe]

Hello good day i am akintewe and i am excited to work on the project .

✍🏼 Background:
I'm a full-stack developer with 4+ years of experience building complex forms and e-commerce systems. I've previously developed inventory management systems for agricultural businesses and am well-versed in handling image processing and state management at scale.

ETA 4 hours

[Dprof-in-tech]

hello @salazarsebas , I am Isaac, i am a part of the OnlyDust fellowship program and i would love to work on this issue.
ETA 24 hours with no blockers

[sotoJ24]

Hello team, I'm Josue Soto, a backend software engineer and open source contributor on OnlyDust fellowship program.
I have skills in problem solving, database schema management, Cairo, Rust, SQL.

How I plan to solve it

1. Create Feature Branch
2. Install Dependencies
3. Create OpenAPI Specification
4. Create Documentation Route
5. Update Main Server
6. Create Unit Tests
7. Validate Documentation
8. Commit Changes

[yhoungdev]

Hey GM @salazarsebas
Recurring contributor; I will add Swagger UI and OpenAPI spec, serve /docs (no auth/rate limit), write a /docs 200 test, and ensure ESLint/Prettier and CI pass. Branch: feat/api-documentation. Commit: feat: add api documentation. Please assign.

[yhoungdev]

Hey @salazarsebas you can assign this to me.