9592971678
- Create api/swagger.md page to properly document Swagger UI access instead of linking raw swagger.json in mkdocs nav - Fix Stop() state management: properly set Running=false and cmd=nil on all exit paths, wait for process termination to avoid zombies 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
62 lines
1.3 KiB
Markdown
62 lines
1.3 KiB
Markdown
# Swagger Documentation
|
|
|
|
Interactive API documentation is available when running the Mining service.
|
|
|
|
## Accessing Swagger UI
|
|
|
|
When the service is running, you can access the Swagger UI at:
|
|
|
|
```
|
|
http://localhost:9090/api/v1/mining/swagger/index.html
|
|
```
|
|
|
|
## Starting the Service
|
|
|
|
=== "CLI"
|
|
|
|
```bash
|
|
miner-ctrl serve
|
|
```
|
|
|
|
=== "Development"
|
|
|
|
```bash
|
|
make dev
|
|
```
|
|
|
|
## OpenAPI Specification
|
|
|
|
The OpenAPI 3.0 specification is available at:
|
|
|
|
- **JSON**: `http://localhost:9090/api/v1/mining/swagger/doc.json`
|
|
- **YAML**: `http://localhost:9090/api/v1/mining/swagger/doc.yaml`
|
|
|
|
## Regenerating Docs
|
|
|
|
After modifying API endpoints, regenerate the Swagger documentation:
|
|
|
|
```bash
|
|
make docs
|
|
```
|
|
|
|
This runs `swag init` to parse the Go annotations and update the specification files.
|
|
|
|
## API Annotations
|
|
|
|
API documentation is generated from Go comments using [swaggo/swag](https://github.com/swaggo/swag). Example:
|
|
|
|
```go
|
|
// StartMiner godoc
|
|
// @Summary Start a miner
|
|
// @Description Start mining with a specific profile
|
|
// @Tags miners
|
|
// @Accept json
|
|
// @Produce json
|
|
// @Param profile_id path string true "Profile ID"
|
|
// @Success 200 {object} MinerResponse
|
|
// @Failure 400 {object} ErrorResponse
|
|
// @Router /miners/{profile_id}/start [post]
|
|
func (s *Service) StartMiner(c *gin.Context) {
|
|
// ...
|
|
}
|
|
```
|