feat(doc/gui): attach Scalar/OpenAPI

[ahmedrowaihi]

[UPDATE]

🎯 OpenAPI 3.1.0 auto-gen | scalar api docs

Adds OpenAPI 3.1.0 specification support with proper schema definitions, error responses, and configurable documentation endpoints.

Quick Start

# Run the server without OpenAPI docs (default)
go run cmd/thv/main.go serve

# Run the server with OpenAPI docs enabled
go run cmd/thv/main.go serve --openapi

# View API docs (when enabled)
curl http://localhost:8080/api/doc

# Get OpenAPI spec (when enabled)
curl http://localhost:8080/api/openapi.json

What's Inside

• OpenAPI 3.1.0 spec with proper schema definitions
• API reference page using Scalar UI
• JSON schema definitions for all endpoints
• Configurable documentation endpoints via --openapi flag
• Improved security by making docs optional
• Updated CLI documentation
• Added comprehensive API documentation guide (docs/api-documentation.md)

Documentation

• Added new docs/api-documentation.md with:
  • Prerequisites and tool installation
  • Step-by-step guide for generating documentation
  • Best practices for API documentation
  • Troubleshooting guide

Documentation Generation

The CLI documentation is generated using Cobra's doc generator. To update the documentation:

1. Install the required tools:

# Install task (if not already installed)
brew install go-task/tap/go-task

# Install swag for OpenAPI generation
go install github.com/swaggo/swag/v2/cmd/swag@v2.0.0-rc4

2. Generate the documentation:

# Generate CLI help docs
task docs

# Generate OpenAPI spec
swag init -g pkg/api/server.go --v3.1

3. Verify the documentation is up to date:

./cmd/help/verify.sh

If the verify script shows differences, run task docs again to regenerate the documentation.

Changes

• Added --openapi flag to control documentation endpoints
• Moved documentation endpoints under /api/ prefix
• Updated Scalar UI configuration
• Regenerated CLI documentation
• Added comprehensive API documentation guide

[ahmedrowaihi]

Anyone hear me 👀

[JAORMX]

Hey! thanks a lot for your contribution. Left some comments, wdyt?

[ahmedrowaihi]

@JAORMX
after trying many tools to auto-gen api docs, I decided to use swag, it worked best after trying many tools

I updated the PR description, all guide and docs are written

[JAORMX]

Thanks for all the work @ahmedrowaihi ! I'll finish the review today, just woke up haha

[JAORMX]

@ahmedrowaihi thanks a lot for these additions! Mind adding some docs to the README? I'll merge this so that can be done in another PR. might be handy to move swag init -g pkg/api/server.go --v3.1 into a task target as well.