From dceb05d3d0517a09a5a9000b046d4ce25a35a86b Mon Sep 17 00:00:00 2001 From: Doug Fennell Date: Fri, 3 Oct 2025 12:00:52 -0500 Subject: [PATCH 1/2] docs(home): fix API Reference link to version-aware relative path (api/) --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 1732587..959598f 100644 --- a/docs/index.md +++ b/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 From 7c62d208a15ea62ab4240f960dbd5a4300d40b84 Mon Sep 17 00:00:00 2001 From: Doug Fennell Date: Fri, 3 Oct 2025 12:07:22 -0500 Subject: [PATCH 2/2] docs(api): add dual views (Reference via Redoc, Playground via Swagger UI); update nav and CI deps --- .github/workflows/docs.yml | 2 ++ docs/api/index.md | 27 +++++++-------------------- docs/api/playground.md | 3 +++ docs/api/reference.md | 6 ++++++ mkdocs.yml | 6 +++++- 5 files changed, 23 insertions(+), 21 deletions(-) create mode 100644 docs/api/playground.md create mode 100644 docs/api/reference.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 832ca17..31412c2 100644 --- a/.github/workflows/docs.yml +++ b/.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: | diff --git a/docs/api/index.md b/docs/api/index.md index 06cf143..2d682f7 100644 --- a/docs/api/index.md +++ b/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) diff --git a/docs/api/playground.md b/docs/api/playground.md new file mode 100644 index 0000000..84f9951 --- /dev/null +++ b/docs/api/playground.md @@ -0,0 +1,3 @@ +# API Playground + + diff --git a/docs/api/reference.md b/docs/api/reference.md new file mode 100644 index 0000000..948f0f9 --- /dev/null +++ b/docs/api/reference.md @@ -0,0 +1,6 @@ +# API Reference + +```redoc +spec-url: ./v1/openapi.json +hide-download-button: true +``` diff --git a/mkdocs.yml b/mkdocs.yml index e49d71e..b26707a 100644 --- a/mkdocs.yml +++ b/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