Merge pull request #1264 from NanaKhadija1980j/feat/1260-openapi-swagger-docs

feat: add OpenAPI/Swagger API documentation (#1260)

Author: OtowoSamuel

Makefile

@@ -24,7 +24,7 @@
 	dev-setup dev-setup-rust dev-setup-tools dev-setup-hooks pre-commit pre-commit-install run run-local run-dev \
 	install-crd apply-samples crd-gen regenerate completions completions-bash completions-zsh completions-fish \
 	helm-lint link-check link-check-all changelog \
-	generate-api-docs check-api-docs check-stale-docs update-doc-baseline docs-check-strict docs-lint \
+	generate-api-docs check-api-docs generate-openapi-spec check-openapi-spec check-stale-docs update-doc-baseline docs-check-strict docs-lint \
 	third-party-licenses check-third-party-licenses sort-manifests \
 	benchmark benchmark-upgrade benchmark-webhook benchmark-webhook-health \
 	benchmark-webhook-compare benchmark-webhook-save benchmark-all \
@@ -282,6 +282,15 @@ check-api-docs: ## Check API docs are up to date (used in CI)
 		--output docs/api-reference.md \
 		--check
 
+generate-openapi-spec: ## Validate operator REST OpenAPI specification
+	@echo "→ Validating OpenAPI specification..."
+	@python3 scripts/generate-openapi-spec.py --spec docs/api/openapi.yaml
+	@echo "✓ docs/api/openapi.yaml is valid"
+
+check-openapi-spec: ## Fail if OpenAPI spec is missing required operator routes
+	@echo "→ Checking OpenAPI spec coverage..."
+	@python3 scripts/generate-openapi-spec.py --spec docs/api/openapi.yaml --check
+
 check-stale-docs: ## Check for documentation that has fallen behind source code (warns; use docs-check-strict to fail)
 	@echo "→ Checking for stale documentation..."
 	@$(CARGO) run --bin doc-check -- --warn-only

README.md

@@ -613,12 +613,20 @@ The full `StellarNode` CRD field reference — including all fields, types, defa
 
 **[docs/api-reference.md](docs/api-reference.md)**
 
-The reference is auto-generated from the CRD OpenAPI schema. To regenerate after modifying the CRD types:
+The CRD reference is auto-generated from the CRD OpenAPI schema. To regenerate after modifying the CRD types:
 
 ```bash
 make generate-api-docs
 ```
 
+Operator REST endpoints are documented in **[docs/api/openapi.yaml](docs/api/openapi.yaml)** (OpenAPI 3.0). Validate coverage with:
+
+```bash
+make check-openapi-spec
+```
+
+Interactive Swagger UI is available at `/developer` when the API gateway is enabled.
+
 ---
 
 ## 💻 Development

docs/api/index.md

@@ -4,13 +4,28 @@ This directory contains the API reference and integration documentation for Stel
 
 ## Contents
 
-- [CRD API Reference](../api-reference.md)
-- [OpenAPI Specification](openapi.yaml)
+- [StellarNode CRD Reference](../api-reference.md) — field-level CRD schema (generated)
+- [OpenAPI Specification](openapi.yaml) — operator REST API (Swagger-compatible)
 - [Webhook API](webhook.md)
 - [Metrics API](metrics.md)
 - [Client Libraries and SDK Guidance](client-libraries.md)
 - [Error Codes and Troubleshooting](error-codes.md)
 
+## Swagger / OpenAPI
+
+| Artifact | Location |
+|----------|----------|
+| Static OpenAPI 3.0 spec | `docs/api/openapi.yaml` |
+| Live JSON (API gateway) | `GET /gateway/openapi.json` |
+| Interactive Swagger UI | `GET /developer` (when gateway enabled) |
+
+Validate the static spec locally:
+
+```bash
+make generate-openapi-spec
+make check-openapi-spec
+```
+
 ## Overview
 
 Stellar-K8s exposes the following integration layers: