mirror of
https://github.com/sonr-io/sonr.git
synced 2026-08-02 17:31:39 +00:00
docs: remove swagger generation config and docs
This commit is contained in:
@@ -1,64 +0,0 @@
|
|||||||
# Sonr API Documentation
|
|
||||||
|
|
||||||
This directory contains the OpenAPI/Swagger documentation for the Sonr blockchain API.
|
|
||||||
|
|
||||||
## Structure
|
|
||||||
|
|
||||||
- `config.json` - Configuration for swagger-combine, defines which module swagger files to merge
|
|
||||||
- `swagger-ui/swagger.yaml` - The unified OpenAPI specification for all Sonr modules
|
|
||||||
|
|
||||||
## Generation Process
|
|
||||||
|
|
||||||
The OpenAPI documentation is generated following the Cosmos SDK standard approach:
|
|
||||||
|
|
||||||
1. **Proto to Swagger**: `buf generate` creates individual swagger JSON files for each module (DID, DWN, Service, DEX) in a temporary directory
|
|
||||||
2. **Combine**: `swagger-combine` merges all module specifications into a single `swagger.yaml` file
|
|
||||||
3. **Cleanup**: Temporary files are removed
|
|
||||||
|
|
||||||
### Generate Documentation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# From the repo root
|
|
||||||
make swagger-gen
|
|
||||||
|
|
||||||
# Or from the proto directory
|
|
||||||
cd proto && make swagger-gen
|
|
||||||
```
|
|
||||||
|
|
||||||
The generated `swagger.yaml` file can be:
|
|
||||||
- Viewed in Swagger UI
|
|
||||||
- Used to generate client SDKs
|
|
||||||
- Embedded in the binary for serving via the API server
|
|
||||||
- Published to API documentation platforms
|
|
||||||
|
|
||||||
## Module Specifications
|
|
||||||
|
|
||||||
The following Sonr modules are included:
|
|
||||||
|
|
||||||
- **DID Module** (`sonr/did/v1`) - Decentralized Identity management
|
|
||||||
- **DWN Module** (`sonr/dwn/v1`) - Decentralized Web Node operations
|
|
||||||
- **Service Module** (`sonr/svc/v1`) - Service registration and management
|
|
||||||
- **DEX Module** (`sonr/dex/v1`) - Decentralized exchange functionality
|
|
||||||
|
|
||||||
Each module contributes both query (read) and transaction (write) endpoints to the unified API specification.
|
|
||||||
|
|
||||||
## Operation ID Conflicts
|
|
||||||
|
|
||||||
To prevent naming conflicts when combining module specifications, the `config.json` file renames common operation IDs with module-specific prefixes:
|
|
||||||
|
|
||||||
- `Params` → `DIDParams`, `DWNParams`, `ServiceParams`, `DEXParams`
|
|
||||||
|
|
||||||
This ensures all operations have unique identifiers in the combined specification.
|
|
||||||
|
|
||||||
## Serving the API Documentation
|
|
||||||
|
|
||||||
The swagger.yaml can be embedded in the Sonr binary and served via the API server. To enable:
|
|
||||||
|
|
||||||
```toml
|
|
||||||
# ~/.snrd/config/app.toml
|
|
||||||
[api]
|
|
||||||
enable = true
|
|
||||||
swagger = true
|
|
||||||
```
|
|
||||||
|
|
||||||
Then access the swagger UI at: `http://localhost:1317/swagger/`
|
|
||||||
@@ -1,54 +0,0 @@
|
|||||||
{
|
|
||||||
"swagger": "2.0",
|
|
||||||
"info": {
|
|
||||||
"title": "Sonr - gRPC Gateway API",
|
|
||||||
"description": "A REST interface for Sonr blockchain state queries and transactions",
|
|
||||||
"version": "1.0.0"
|
|
||||||
},
|
|
||||||
"apis": [
|
|
||||||
{
|
|
||||||
"url": "../../tmp-swagger-gen/sonr/did/v1/query.swagger.json",
|
|
||||||
"operationIds": {
|
|
||||||
"rename": {
|
|
||||||
"Params": "DIDParams"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"url": "../../tmp-swagger-gen/sonr/did/v1/tx.swagger.json"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"url": "../../tmp-swagger-gen/sonr/dwn/v1/query.swagger.json",
|
|
||||||
"operationIds": {
|
|
||||||
"rename": {
|
|
||||||
"Params": "DWNParams"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"url": "../../tmp-swagger-gen/sonr/dwn/v1/tx.swagger.json"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"url": "../../tmp-swagger-gen/sonr/svc/v1/query.swagger.json",
|
|
||||||
"operationIds": {
|
|
||||||
"rename": {
|
|
||||||
"Params": "ServiceParams"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"url": "../../tmp-swagger-gen/sonr/svc/v1/tx.swagger.json"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"url": "../../tmp-swagger-gen/sonr/dex/v1/query.swagger.json",
|
|
||||||
"operationIds": {
|
|
||||||
"rename": {
|
|
||||||
"Params": "DEXParams"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"url": "../../tmp-swagger-gen/sonr/dex/v1/tx.swagger.json"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
Reference in New Issue
Block a user