developer-docs: publish the REST API OpenAPI 3.0 specification

[vihar]

Summary

• Publishes the OpenAPI 3.0 specification of the Plane public REST API (69 paths, 130 operations, API-key auth, request/response examples) at https://developers.plane.so/openapi.json and /openapi.yaml. Until now no machine-readable spec existed anywhere online: ENABLE_DRF_SPECTACULAR is off on Plane Cloud (api.plane.so/api/schema/ 404s) and the docs only described self-host generation. This was the single biggest gap in the is-agentic audit for developers.plane.so.
• The published copy puts the production server (https://api.plane.so) first so generators and agents default to it; the spec is otherwise exactly what drf-spectacular emits from makeplane/plane@preview (ENABLE_DRF_SPECTACULAR=1 python manage.py spectacular).
• Links the spec from the llms.txt Optional section, adds an "OpenAPI specification" section to the API reference introduction, and restructures the OpenAPI docs page to lead with the hosted download before the self-host generation instructions.
• Adds the two spec files to the oxfmt ignore list (generated artifacts).

Maintenance note: the spec is a committed snapshot and should be regenerated when the API changes — the generation command is documented on the OpenAPI page and in the commit message. Happy to add a CI job for that as a follow-up if wanted.

Test plan

• pnpm check and pnpm --filter developer-docs build pass (verified locally)
• Built dist serves /openapi.json (valid JSON, production server first) and llms.txt links it (verified locally)
• After deploy: curl -s https://developers.plane.so/openapi.json | jq .info.title returns "The Plane REST API"
• Spot-check the spec in an OpenAPI viewer (e.g. Swagger Editor) for rendering errors

Made with Cursor

Summary by CodeRabbit

• Documentation
  • Added links to the published OpenAPI 3.0 JSON and YAML specifications.
  • Documented how to access, download, and use the OpenAPI specification.
  • Added guidance for generating the specification in self-hosted environments.
  • Included browser, curl, and offline command examples for retrieving the schema.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
developer-docs	Ready	Preview	Aug 22, 2026 1:00pm
docs	Ready	Preview	Aug 22, 2026 1:00pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a0329a1b-6778-4999-a8aa-da7dbadf25d7

📥 Commits

Reviewing files that changed from the base of the PR and between d5d57af and bd21c6e.

📒 Files selected for processing (6)

• .oxfmtrc.json
• apps/developer-docs/docs/.vitepress/config.mts
• apps/developer-docs/docs/api-reference/introduction.md
• apps/developer-docs/docs/dev-tools/openapi-specification.md
• apps/developer-docs/docs/public/openapi.json
• apps/developer-docs/docs/public/openapi.yaml

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR documents published OpenAPI JSON and YAML specifications, adds self-hosted generation guidance, updates LLM documentation links, and excludes generated specifications from formatter processing.

Changes

OpenAPI documentation

Layer / File(s)	Summary
Published specification access apps/developer-docs/docs/.vitepress/config.mts, apps/developer-docs/docs/api-reference/introduction.md, apps/developer-docs/docs/dev-tools/openapi-specification.md	The documentation links to the hosted JSON and YAML specifications and adds the OpenAPI specification to the optional LLM documentation links.
Self-hosted generation and document structure .oxfmtrc.json, apps/developer-docs/docs/dev-tools/openapi-specification.md	The guide documents self-hosted generation, schema access methods, and offline commands. Generated OpenAPI files are excluded from formatter processing. Related headings now use deeper nesting.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to bd21c

This PR publishes the REST API OpenAPI specification and updates documentation links so API consumers can discover it. No actionable merge-blocking risk remains; it is merge-ready after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: publishing the developer documentation and REST API OpenAPI 3.0 specification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1 files. (3 skipped: 3 unsupported.)
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch developer-docs/publish-openapi-spec

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}