mirror of
https://github.com/sonr-io/sonr.git
synced 2026-08-02 17:31:39 +00:00
65 lines
2.1 KiB
Markdown
65 lines
2.1 KiB
Markdown
# 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/`
|