docs(platform): fix api reference internal links; add OpenAPI spec + viewer

- Fix intra-group and cross-section relative links to satisfy the repo's
  extra-"../" convention (verified with the CI liche fork + -s): same-directory
  siblings use ../<file>, cross-group/section links get one additional ../.
- Add docs/platform/api/openapi.yaml — the machine-readable OpenAPI 3.0.3 spec,
  served verbatim as a page resource and linked from the API reference index.
- Add api.html at the repo root — a self-contained Swagger UI viewer with the
  spec inlined (kept out of docs/ so the link checker does not scan its inlined
  URLs and Hugo does not wrap it in the site theme).

Signed-off-by: Tamal Saha <tamal@appscode.com>

Author: tamalsaha

api.html

@@ -32,27 +32,31 @@ endpoints accept HTTP Basic auth. The web console uses a session cookie
 (`i_like_ace`); a session cookie alone does **not** authenticate the token-guarded
 REST endpoints — use a token.
 
-A machine-readable OpenAPI 3.0.3 description of this API is also available.
+A machine-readable [OpenAPI 3.0.3 specification](../openapi.yaml) of this API is also
+available (`openapi.yaml`) — load it into any OpenAPI tool (Swagger UI, Redoc,
+`openapi-generator`) to explore the API or generate a client. A self-contained
+Swagger UI viewer (`api.html`, with the spec inlined) is available at the repository
+root.
 
 ## API groups
 
 | Group | What it covers |
 |---|---|
-| [Identity: Users & Settings](users-settings/) | Accounts, profile/security settings, tokens, credentials |
-| [Identity: Organizations & Teams](organizations-teams/) | Orgs, members, teams, org tokens |
-| [Administration](administration/) | Admin console, site settings |
-| [Authorization](authorization/) | Custom roles & permissions |
-| [Cluster Management v1](cluster-management-v1/) | Cluster lifecycle, Kubernetes proxy, Helm |
-| [Cluster Management v2](cluster-management-v2/) | Hub-aware cluster API, subscriptions, gateways |
-| [Multi-cluster (OCM)](multicluster-ocm/) | Hub/spoke, cluster sets, feature sets |
-| [Client Organizations](client-organizations/) | Managed-service client orgs |
-| [Cloud Providers](cloud-providers/) | Provider discovery for provisioning |
-| [ACE Installer](ace-installer/) | Self-host installer bundles |
-| [ACE Upgrade](ace-upgrade/) | Platform & cluster upgrades |
-| [Licensing & Contracts](licensing-contracts/) | Contracts, licenses, registration |
-| [Billing Dashboard](billing-dashboard/) | Usage reports & billing dashboards |
-| [Marketplace](marketplace/) | Cloud-marketplace webhooks & metering |
-| [Monitoring & Telemetry](monitoring-telemetry/) | Telemetry stack, Trickster auth proxy |
-| [Rancher Integration](rancher/) | Rancher sync & proxy |
-| [Chart Repositories](chart-repositories/) | Public Helm chart repositories |
-| [Miscellaneous](miscellaneous/) | Version, markdown, health |
+| [Identity: Users & Settings](../users-settings/) | Accounts, profile/security settings, tokens, credentials |
+| [Identity: Organizations & Teams](../organizations-teams/) | Orgs, members, teams, org tokens |
+| [Administration](../administration/) | Admin console, site settings |
+| [Authorization](../authorization/) | Custom roles & permissions |
+| [Cluster Management v1](../cluster-management-v1/) | Cluster lifecycle, Kubernetes proxy, Helm |
+| [Cluster Management v2](../cluster-management-v2/) | Hub-aware cluster API, subscriptions, gateways |
+| [Multi-cluster (OCM)](../multicluster-ocm/) | Hub/spoke, cluster sets, feature sets |
+| [Client Organizations](../client-organizations/) | Managed-service client orgs |
+| [Cloud Providers](../cloud-providers/) | Provider discovery for provisioning |
+| [ACE Installer](../ace-installer/) | Self-host installer bundles |
+| [ACE Upgrade](../ace-upgrade/) | Platform & cluster upgrades |
+| [Licensing & Contracts](../licensing-contracts/) | Contracts, licenses, registration |
+| [Billing Dashboard](../billing-dashboard/) | Usage reports & billing dashboards |
+| [Marketplace](../marketplace/) | Cloud-marketplace webhooks & metering |
+| [Monitoring & Telemetry](../monitoring-telemetry/) | Telemetry stack, Trickster auth proxy |
+| [Rancher Integration](../rancher/) | Rancher sync & proxy |
+| [Chart Repositories](../chart-repositories/) | Public Helm chart repositories |
+| [Miscellaneous](../miscellaneous/) | Version, markdown, health |

docs/platform/api/_index.md

@@ -27,6 +27,6 @@ and supports reconfigure/upgrade/versioning and marketplace-installer status.
 
 ## Pages
 
-- [ACE Installer](../ace-installer/ace-installer.md) — schema/model, generate/import,
+- [ACE Installer](../ace-installer.md) — schema/model, generate/import,
   installer metadata and latest version, installers CRUD, reconfigure/upgrade,
   versions/archives, and marketplace installer status.

docs/platform/api/ace-installer/_index.md

@@ -35,11 +35,11 @@ across two pages:
 
 ## Pages
 
-- [Platform Upgrade](../ace-upgrade/platform-upgrade.md) — the
+- [Platform Upgrade](../platform-upgrade.md) — the
   `/api/v1/upgrade*` endpoints: platform upgrade status, job status, history, and
   current version, plus triggering a platform upgrade. Requires site-admin org
   authorization.
-- [Cluster Upgrade](../ace-upgrade/cluster-upgrade.md) — the
+- [Cluster Upgrade](../cluster-upgrade.md) — the
   `/api/v1/clusters/{owner}/{cluster}/upgrade*` and `.../spoke/upgrade*`
   endpoints: imported-cluster and spoke-cluster upgrade status, history, current
   and latest versions, plus triggering cluster/spoke upgrades. Gated by cluster

docs/platform/api/ace-upgrade/_index.md

@@ -31,6 +31,6 @@ required.
 
 ## Pages
 
-- [Administrative-Org Admin](../administration/admin-org.md) — `/api/v1/admin/*`: manage users and their organizations.
-- [Site Admin Console](../administration/site-admin-console.md) — `/api/v1/accounts/admin/*`: dashboard, users, orgs, clusters, auth sources.
-- [Site Settings](../administration/site-settings.md) — `/allowed-domains`, `/disable-registration`, `/branding`.
+- [Administrative-Org Admin](../admin-org.md) — `/api/v1/admin/*`: manage users and their organizations.
+- [Site Admin Console](../site-admin-console.md) — `/api/v1/accounts/admin/*`: dashboard, users, orgs, clusters, auth sources.
+- [Site Settings](../site-settings.md) — `/allowed-domains`, `/disable-registration`, `/branding`.

docs/platform/api/administration/_index.md

@@ -26,6 +26,6 @@ and membership of that organization are required.
 
 ## Pages
 
-- [Roles & Permissions](../authorization/roles-permissions.md) — object
+- [Roles & Permissions](../roles-permissions.md) — object
   allowed-permissions lookups (single and batch), the available-permissions
   catalog, role CRUD, and role principal listings.

docs/platform/api/authorization/_index.md

@@ -46,13 +46,13 @@ Routes in this group fall into three authorization tiers:
 
 ## Pages
 
-- [Admin Billing Dashboard](../billing-dashboard/admin-dashboard.md) — the
+- [Admin Billing Dashboard](../admin-dashboard.md) — the
   site-admin `/api/v1/dashboard/*` routes: licensed users, their clusters,
   per-cluster licenses and licensed products, resource/event histories, marketplace
   subscriptions, and system-outage records.
-- [User Billing Dashboard](../billing-dashboard/user-dashboard.md) — the
+- [User Billing Dashboard](../user-dashboard.md) — the
   owner-scoped `/api/v1/dashboard/clusters/*` routes (`view:contracts`): an
   organization's own active clusters, licenses, licensed products, and event counts.
-- [Usage Reports](../billing-dashboard/usage-reports.md) — the
+- [Usage Reports](../usage-reports.md) — the
   `/api/v1/dashboard/summary/*` monthly usage-report views and PDF download, plus
   the `/api/v1/dbaas/billing/*` namespace billing reports.

docs/platform/api/billing-dashboard/_index.md

@@ -83,7 +83,7 @@ Returns cluster information for a cluster owned by the request owner.
 | `cid` | string | Cluster UID. |
 
 - **Response:** `200 OK` — a single `ClusterInfo` object (the same shape documented
-  on the [Admin Billing Dashboard](../billing-dashboard/admin-dashboard.md) page;
+  on the [Admin Billing Dashboard](../admin-dashboard.md) page;
   `status` is a free-form Kubernetes-style object). `404` if the cluster is unknown
   or not owned by the org.
 

docs/platform/api/billing-dashboard/user-dashboard.md

@@ -25,6 +25,6 @@ role is required. Only `GET` requests are exposed here.
 
 ## Pages
 
-- [Chart Repositories](../chart-repositories/chart-repositories.md) — list the
+- [Chart Repositories](../chart-repositories.md) — list the
   known chart repositories, list the charts inside a repository, and list the
   versions of a named chart.

docs/platform/api/chart-repositories/_index.md

@@ -19,11 +19,11 @@ user access on behalf of each client.
 
 There are two concerns, split across two pages:
 
-- [Client Org Management](../client-organizations/management.md) — site-admin
+- [Client Org Management](../management.md) — site-admin
   lifecycle of client organizations: list/get/create/delete client orgs, add or
   remove clusters, and query client-org status. Routes live under
   `/api/v1/user/client*`.
-- [Cluster User Permissions](../client-organizations/cluster-user-permissions.md)
+- [Cluster User Permissions](../cluster-user-permissions.md)
   — organization-admin management of the OCM users belonging to a client org on
   a specific cluster: list users, create a user with permissions, inspect and
   update permissions, generate a kubeconfig, and remove a user. Routes live