developer-docs: publish the REST API OpenAPI 3.0 specification

.oxfmtrc.json

@@ -4,6 +4,8 @@
     "pnpm-lock.yaml",
     "**/.vitepress/cache/**",
     "**/.vitepress/dist/**",
-    "**/.turbo/**"
+    "**/.turbo/**",
+    "apps/developer-docs/docs/public/openapi.json",
+    "apps/developer-docs/docs/public/openapi.yaml"
   ]
 }

apps/developer-docs/docs/.vitepress/config.mts

@@ -88,6 +88,7 @@ export default extendConfig(
                 "- [Roles and permissions](https://docs.plane.so/roles-and-permissions/overview.md): What each workspace and project role is allowed to do.",
               ].join("\n"),
               optional: [
+                "- [OpenAPI 3.0 specification (JSON)](https://developers.plane.so/openapi.json): Machine-readable description of every Plane REST API endpoint; also available as [YAML](https://developers.plane.so/openapi.yaml).",
                 "- [Complete documentation in one file](https://developers.plane.so/llms-full.txt): Every page of developers.plane.so concatenated as Markdown (about 1.6 MB).",
                 "- [Sitemap](https://developers.plane.so/sitemap.xml): Every page URL on developers.plane.so.",
                 "- [Plane on GitHub](https://github.com/makeplane/plane): Source code, issues, and releases.",

apps/developer-docs/docs/api-reference/introduction.md

@@ -28,6 +28,15 @@ GET https://api.plane.so/api/v1/workspaces/{workspace_slug}/projects/
 If you're using a self-hosted instance of Plane, your API base URL will differ based on your custom domain and setup.
 :::
 
+## OpenAPI specification
+
+The complete API is described by an OpenAPI 3.0 specification — useful for generating clients, validating requests, or giving AI agents a machine-readable view of every endpoint:
+
+- [openapi.json](https://developers.plane.so/openapi.json)
+- [openapi.yaml](https://developers.plane.so/openapi.yaml)
+
+See [OpenAPI Specification](/dev-tools/openapi-specification) for how the spec is produced and how to generate one from a self-hosted instance.
+
 ## Authentication
 
 Our APIs use a key for authentication. The API key should be included in the header of each request to verify the client's identity and permissions. The key should be passed as the value of the `X-API-Key` header.

apps/developer-docs/docs/dev-tools/openapi-specification.md

@@ -6,9 +6,24 @@ keywords: plane, developer tools, openapi, api specification, swagger, redoc, dr
 
 # OpenAPI Specification
 
-Plane uses [drf-spectacular](https://drf-spectacular.readthedocs.io/) to generate an OpenAPI 3.0 specification for the public REST API (`/api/v1/`). The feature is **disabled by default** and must be explicitly enabled.
+Plane uses [drf-spectacular](https://drf-spectacular.readthedocs.io/) to generate an OpenAPI 3.0 specification for the public REST API (`/api/v1/`).
 
-## Enable the OpenAPI spec
+## Download the published spec
+
+The specification is published with these docs — point code generators, API clients, and AI agents at either file:
+
+| Format | URL                                                                          |
+| ------ | ---------------------------------------------------------------------------- |
+| JSON   | [developers.plane.so/openapi.json](https://developers.plane.so/openapi.json) |
+| YAML   | [developers.plane.so/openapi.yaml](https://developers.plane.so/openapi.yaml) |
+
+The published spec lists `https://api.plane.so` (Plane Cloud) as the production server. When self-hosting, replace it with your own domain, or generate the spec from your own instance as described below.
+
+## Generate the spec from a self-hosted instance
+
+The schema endpoints are **disabled by default** and must be explicitly enabled.
+
+### Enable the OpenAPI spec
 
 Add the following to your `.env` file (at the project root or `apps/api/.env`):
 
@@ -24,7 +39,7 @@ Then restart the API server so it picks up the new variable.
 
 No other environment variables are needed — everything else (schema path prefix, tags, auth schemes, servers) is pre-configured in `apps/api/plane/settings/openapi.py`.
 
-## Access the OpenAPI spec
+### Access the OpenAPI spec
 
 > Replace `{domain_name}` below with your self-hosted Plane domain (e.g. `plane.example.com`).
 
@@ -36,9 +51,9 @@ Once the API server is running with the variable enabled, three endpoints are av
 | `GET /api/schema/swagger-ui/` | `https://{domain_name}/api/schema/swagger-ui/` | Interactive Swagger UI     |
 | `GET /api/schema/redoc/`      | `https://{domain_name}/api/schema/redoc/`      | ReDoc documentation viewer |
 
-## Download the OpenAPI spec
+### Download the OpenAPI spec
 
-### Browser
+#### Browser
 
 Open `https://{domain_name}/api/schema/` and save the page. The default format is YAML.
 
@@ -48,7 +63,7 @@ For JSON, append the `format` query parameter:
 https://{domain_name}/api/schema/?format=openapi-json
 ```
 
-### curl
+#### curl
 
 ```bash
 # YAML
@@ -58,7 +73,7 @@ curl -o openapi.yaml https://{domain_name}/api/schema/
 curl -o openapi.json https://{domain_name}/api/schema/?format=openapi-json
 ```
 
-### Management command (offline, no running server required)
+#### Management command (offline, no running server required)
 
 ```bash
 # From apps/api/