sonr/client/docs/README.md

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

# 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:

# ~/.snrd/config/app.toml
[api]
enable = true
swagger = true

Then access the swagger UI at: http://localhost:1317/swagger/