docs(api): provide Reference (Redoc) and Playground (Swagger UI)

.github/workflows/docs.yml

@@ -30,6 +30,7 @@ jobs:
           pip install mkdocs-material
           pip install mkdocs-git-revision-date-localized-plugin
           pip install mkdocs-redoc-tag
+          pip install mkdocs-swagger-ui-tag
       - name: MkDocs build (no deploy)
         run: mkdocs build --strict
 
@@ -53,6 +54,7 @@ jobs:
           pip install mkdocs-material
           pip install mkdocs-git-revision-date-localized-plugin
           pip install mkdocs-redoc-tag
+          pip install mkdocs-swagger-ui-tag
           pip install mike
       - name: Deploy with versioning
         run: |

docs/api/index.md

@@ -1,24 +1,11 @@
-# RDCP OpenAPI (v1)
+# API Documentation
 
-This page renders the RDCP OpenAPI contract for version 1.
+RDCP provides two ways to explore the API:
 
-!!! note "Multi-tenancy header and server hostname"
-    - X-RDCP-Tenant-ID: Optional header used in multi-tenant deployments to scope discovery, control, status and metrics to a specific tenant.
-    - Format: an opaque string up to 255 chars matching `^[a-zA-Z0-9._-]{1,255}$`.
-    - Supported endpoints: `/rdcp/v1/discovery`, `/rdcp/v1/control`, `/rdcp/v1/status`, `/rdcp/v1/metrics`.
-    - Servers: the spec defines a templated server `https://{hostname}` with default `localhost:3000`. Replace `{hostname}` with your deployment's host.
+## [API Reference](reference.md)
+Clean, readable documentation of all endpoints, schemas, and responses.
 
-```redoc
-spec-url: ./v1/openapi.json
-hide-download-button: true
-```
+## [API Playground](playground.md)
+Interactive testing environment - try API calls directly from your browser.
 
-Example (curl):
-
-```bash path=null start=null
-HOST=rdcp.example.com
-TENANT=acme-prod
-curl -fsS \
-  -H "X-RDCP-Tenant-ID: $TENANT" \
-  "https://$HOST/rdcp/v1/status"
-```
+Both views use the same OpenAPI specification: [openapi.json](v1/openapi.json)

docs/api/playground.md

@@ -0,0 +1,3 @@
+# API Playground
+
+<swagger-ui src="./v1/openapi.json"></swagger-ui>

docs/api/reference.md

@@ -0,0 +1,6 @@
+# API Reference
+
+```redoc
+spec-url: ./v1/openapi.json
+hide-download-button: true
+```

docs/index.md

@@ -51,7 +51,7 @@ All RDCP-compliant implementations must expose these endpoints:
 
 ## Documentation Structure
 
-- **[API Reference](/api/)** - Interactive OpenAPI (v1) with try-it examples
+- **[API Reference](api/)** - Interactive OpenAPI (v1) with try-it examples
 - **[Protocol Specification](rdcp-protocol-specification.md)** - Complete technical specification
 - **[Implementation Guide](rdcp-implementation-guide.md)** - Step-by-step implementation instructions
 - **[Protocol Schemas](protocol-schemas.md)** - JSON schema definitions

mkdocs.yml

@@ -46,6 +46,7 @@ plugins:
       enable_creation_date: true
       type: datetime
   - redoc-tag
+  - swagger-ui-tag
 
 # Extensions
 markdown_extensions:
@@ -87,6 +88,9 @@ nav:
       - Health Response: schemas/endpoints/health-response.md
     - Response Types:
       - Error Response: schemas/responses/error.md
-  - API Reference: api/index.md
+  - API:
+    - Overview: api/index.md
+    - Reference: api/reference.md
+    - Playground: api/playground.md
   - Error Codes: error-codes.md
   - Compliance Report: PROTOCOL-COMPLIANCE-REPORT.md