[FEAT] Auto-generated OpenAPI docs with drf-spectacular

[chandrasekharan-zipstack]

What

• Replace drf-yasg with drf-spectacular for OpenAPI 3.0 schema generation
• Add @extend_schema annotations with tags, summaries, and descriptions to all Platform API endpoints (86 endpoints across 6 tags)
• Add help_text to model and serializer fields for field-level API documentation
• Create preprocessing hook to filter schema to curated Platform API surface
• Serve ReDoc UI at /api/v1/doc/ and raw schema at /api/v1/doc/schema/

Why

• Onprem customers need proper API documentation for CI/CD automation via Platform API Keys
• drf-yasg is unmaintained (last release 2022) and only supports OpenAPI 2.0
• drf-spectacular auto-infers from DRF ViewSets/Serializers with zero migration cost

How

• Swapped drf-yasg dependency for drf-spectacular>=0.27.0 in pyproject.toml
• Added SPECTACULAR_SETTINGS in base.py with Bearer-only auth, curated tags, and preprocessing/postprocessing hooks
• Created docs/spectacular_hooks.py with exact path+method whitelist filter
• Added @extend_schema / @extend_schema_view decorators to all view files
• Added help_text to Django model fields (no migrations needed - metadata only)
• Fixed incorrect response schemas on Prompt Studio endpoints that return raw dicts

Can this PR break any existing features. If yes, please list possible items. If no, please explain why.

• No. This only adds API documentation metadata. No business logic changes.
• The drf-yasg → drf-spectacular swap changes the doc UI library but the /api/v1/doc/ path is preserved.
• help_text on model fields is metadata-only and does not generate database migrations.

Database Migrations

• None. help_text is Django metadata that does not affect the database schema.

Env Config

• No new environment variables required.

Relevant Docs

• drf-spectacular: https://drf-spectacular.readthedocs.io/
• Companion PR in unstract-docs repo for Docusaurus integration

Related Issues or PRs

• Related to Platform API Keys PR UN-3318 [FEAT] Platform API key implementation #1860

Dependencies Versions

• Removed: drf-yasg>=1.21.8
• Added: drf-spectacular>=0.27.0 (resolved to 0.29.0)

Notes on Testing

• Build backend and verify /api/v1/doc/ serves ReDoc UI
• Verify /api/v1/doc/schema/?format=json returns valid OpenAPI 3.0 with 86 endpoints across 6 tags
• Verify no Django internals leak into schema descriptions

Checklist

I have read and understood the Contribution Guidelines.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e3d04c97-9039-412b-b7e4-ebc93b5a726c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/api-docs-drf-spectacular

📝 Coding Plan

• Generate coding plan for human review comments

---

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 and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud