63 lines
1.3 KiB
Markdown
63 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) {
|
||
|
|
// ...
|
||
|
|
}
|
||
|
|
```
|