🔑 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.yamlsrc/routes/docs.jstests/routes/docs.test.jspackage.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
📋 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.
🔑 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.yamland integrate Swagger UI to serve interactive documentation at/docs, with a unit test to verify accessibility.🗂 Structure
services/stellar-walletdocs/api.yamlsrc/routes/docs.jstests/routes/docs.test.jspackage.json(updated)✅ Requirements
feat/api-documentationfor this task.npm install swagger-ui-express yamljs.package.jsonto includeswagger-ui-expressandyamljsas dependencies.docs/api.yamlto 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)api.yaml:src/routes/docs.jsto serve Swagger UI at/docsusingswagger-ui-express, loading theapi.yamlspecification.src/index.jsto mount the documentation route at/docswithout JWT or rate-limiting middleware.tests/routes/docs.test.jsto verify that the/docsendpoint returns HTTP 200 and serves the Swagger UI.feat/api-documentationbranch with a message likefeat: add api documentation.🏆 Expected Outcomes
swagger-ui-expressandyamljsare installed and listed inpackage.json.docs/api.yamlcontains a complete OpenAPI 3.0 specification for all API endpoints.src/routes/docs.jsserves Swagger UI at/docs, displaying interactive documentation./docsendpoint is accessible without authentication or rate limiting.tests/routes/docs.test.jsconfirms the/docsendpoint returns HTTP 200.feat/api-documentationbranch with a descriptive lowercase commit message.src/routes/docs.jsandtests/routes/docs.test.js, and the unit test passing.🔗 References
📋 Notes
/kyc/submit) and responses.api.yamlto illustrate typical inputs and outputs./docsendpoint should be publicly accessible to facilitate developer onboarding.feat,change,fix,chore, orrefactor.