Create The Developer Integration Guide Which Includes the API Reference, OpenAPI Spec & Quickstart

[grantfox-oss]

Overview

SaviTools exposes a NestJS API that CrowdPay, Fluxa, and external developers will call directly. There is currently no documentation for these endpoints beyond the source code itself. Without a clear API contract, integrators have nothing to build against, errors are opaque, and onboarding new contributors takes longer than it should. This issue covers auto-generating an OpenAPI spec from the codebase and producing a complete written integration guide alongside it.

What needs to be built

OpenAPI / Swagger (in-app)

• Add @nestjs/swagger to apps/api and decorate all controllers, DTOs, and response classes
• Serve Swagger UI at /api/docs in development and staging environments only (disabled in production)
• Spec must cover every existing and planned module: network, composer, sandbox, inspector, simulator, webhooks
• All response shapes must include example values — no empty schemas
  docs/api-reference.md

Sections:

• Base URLs — testnet vs mainnet environments, versioning strategy
• Authentication — API key header format (X-SaviTools-Key), where to generate keys, which endpoints require auth
• Endpoint catalogue — for every endpoint: method + path, description, full request params/body schema, full response schema, and at least one curl example
• Error reference — Stellar/Horizon pass-through error codes vs SaviTools-originated errors, with meaning and suggested resolution for each
• Caching behaviour — which endpoints are Redis-cached, TTL per endpoint, how to bust the cache in development
  docs/quickstart.md

End-to-end walkthrough: "From zero to a submitted Stellar transaction in 5 minutes"

1. Generate a keypair via /sandbox/keypair
2. Fund it on testnet via /sandbox/fund
3. Inspect the account via /sandbox/account/:publicKey
4. Find a payment path via /simulator/paths
5. Build a transaction via /composer/build
6. Submit and inspect the result via /inspector
   Each step includes the exact curl command, expected response, and a note on what could go wrong.

README.md updates

• Link to /api/docs, docs/api-reference.md, and docs/quickstart.md from the root README
• Add a "Documentation" section above "Contributing"

Acceptance Criteria

• Swagger UI loads at /api/docs with all endpoints documented including request/response schemas and examples
• Every endpoint in api-reference.md has at least one working curl example tested against the testnet environment
• Quickstart guide is verified end-to-end on a clean testnet environment with no missing steps or broken commands
• Docs are linked from the root README.md
• Swagger is disabled (returns 404) when NODE_ENV=production

[Enemuo-debug]

Please can this issue be assigned to me?

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[bytebinders]

I've reviewed the requirements and would be happy to work on this issue. I'll deliver comprehensive, production-ready API documentation, Swagger integration, and validated integration guides.

[bytebinders]

Overview

SaviTools exposes a NestJS API that CrowdPay, Fluxa, and external developers will call directly. There is currently no documentation for these endpoints beyond the source code itself. Without a clear API contract, integrators have nothing to build against, errors are opaque, and onboarding new contributors takes longer than it should. This issue covers auto-generating an OpenAPI spec from the codebase and producing a complete written integration guide alongside it.

What needs to be built

OpenAPI / Swagger (in-app)

• Add @nestjs/swagger to apps/api and decorate all controllers, DTOs, and response classes
• Serve Swagger UI at /api/docs in development and staging environments only (disabled in production)
• Spec must cover every existing and planned module: network, composer, sandbox, inspector, simulator, webhooks
• All response shapes must include example values — no empty schemas
  docs/api-reference.md

Sections:

• Base URLs — testnet vs mainnet environments, versioning strategy
• Authentication — API key header format (X-SaviTools-Key), where to generate keys, which endpoints require auth
• Endpoint catalogue — for every endpoint: method + path, description, full request params/body schema, full response schema, and at least one curl example
• Error reference — Stellar/Horizon pass-through error codes vs SaviTools-originated errors, with meaning and suggested resolution for each
• Caching behaviour — which endpoints are Redis-cached, TTL per endpoint, how to bust the cache in development
  docs/quickstart.md

End-to-end walkthrough: "From zero to a submitted Stellar transaction in 5 minutes"

1. Generate a keypair via /sandbox/keypair
2. Fund it on testnet via /sandbox/fund
3. Inspect the account via /sandbox/account/:publicKey
4. Find a payment path via /simulator/paths
5. Build a transaction via /composer/build
6. Submit and inspect the result via /inspector
   Each step includes the exact curl command, expected response, and a note on what could go wrong.

README.md updates

• Link to /api/docs, docs/api-reference.md, and docs/quickstart.md from the root README
• Add a "Documentation" section above "Contributing"

Acceptance Criteria

• Swagger UI loads at /api/docs with all endpoints documented including request/response schemas and examples[ ] Every endpoint in api-reference.md has at least one working curl example tested against the testnet environment[ ] Quickstart guide is verified end-to-end on a clean testnet environment with no missing steps or broken commands[ ] Docs are linked from the root README.md[ ] Swagger is disabled (returns 404) when NODE_ENV=production

I can do this clean and professional

[sankie13]

Hi! I would like to contribute to this issue.

I have experience with backend development using Java, .NET and Python, and I am interested in contributing to open source projects by improving developer experience and API usability.

I reviewed the requirements and I can help with the OpenAPI/Swagger integration, API reference documentation, quickstart guide, and README updates. My approach would be to first review the existing controllers, DTOs, and API flows, then document the endpoints with accurate request/response examples and keep the documentation aligned with the current codebase.

I am also interested in learning and applying the NestJS Swagger workflow while contributing clean and maintainable documentation.

I will follow the existing project conventions and make sure the final documentation is clear for developers integrating with SaviTools.

[blurbeast]

hello my Chief , can i jump on this please ??

[grantfox-oss]

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

Good luck! Track your progress on GrantFox.