docs(client): add OpenAPI/Swagger documentation for Sonr blockchain API

2026-08-02 17:31:39 +00:00 · 2025-10-21 12:04:31 -04:00
parent 53a34171e8
commit cf1712c2d8
2 changed files with 118 additions and 0 deletions
@@ -0,0 +1,64 @@
+# 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/`
@@ -0,0 +1,54 @@
+{
+  "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"
+    }
+  ]
+}