docs(API): add tags to swagger and order them based on workflow

[Holmus]

Thanks for submitting a PR! Please check the boxes below:

• I have read the Contributing Guide.
• I have added information to docs/ if required so people know about the feature.
• I have filled in the "Changes" section below.
• I have filled in the "How did you test this code" section below.

Changes

The Swagger UI at /api/v1/docs/ previously grouped all 443 operations under a single api tag, making it difficult to navigate. This PR adds logical tag grouping via drf-spectacular preprocessing and postprocessing hooks, splitting operations into 20 sections based on URL path patterns (e.g. Organisations, Projects, Features, Integrations). Operations with explicit tags (sdk, mcp, experimental) are left unchanged. The Swagger UI now displays sections in workflow order - Authentication first, then core resources, then configuration/admin.

How did you test this code?

1. Ran the full openapi unit test suite: pytest tests/unit/api/test_unit_openapi.py tests/unit/api/test_mcp_openapi.py
2. Generated the schema locally and verified all 443 operations are assigned to the correct tags with zero unmatched operations.
3. Verified the MCP schema generation still works correctly (postprocessing preserves explicit tags).
4. Ran locally and visually verified result.

[vercel]

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

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs	Ignored	Preview	May 22, 2026 11:43am
flagsmith-frontend-preview	Ignored	Preview	May 22, 2026 11:43am
flagsmith-frontend-staging	Ignored	Preview	May 22, 2026 11:43am

[github-actions]

Docker builds report

Image	Build Status	Security report
ghcr.io/flagsmith/flagsmith-e2e:pr-6885	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-api-test:pr-6885	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-frontend:pr-6885	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith:pr-6885	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-private-cloud:pr-6885	Finished ✅	Results ✅

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Free Tier Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Default preprocessing hook dropped when overriding PREPROCESSING_HOOKS
  • I restored drf_spectacular.hooks.preprocess_exclude_path_format in PREPROCESSING_HOOKS so the default format-suffix path deduplication is preserved alongside the custom hook.

Or push these changes by commenting:

@cursor push bb2444f165

Preview (bb2444f165)

diff --git a/api/app/settings/common.py b/api/app/settings/common.py
--- a/api/app/settings/common.py
+++ b/api/app/settings/common.py
@@ -543,6 +543,7 @@
         "environments.identities.traits.openapi",
     ],
     "PREPROCESSING_HOOKS": [
+        "drf_spectacular.hooks.preprocess_exclude_path_format",
         "api.openapi.preprocessing_filter_spec",
     ],
     "POSTPROCESSING_HOOKS": [

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.50%. Comparing base (2be8504) to head (6b1171e).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6885      +/-   ##
==========================================
+ Coverage   98.49%   98.50%   +0.01%     
==========================================
  Files        1417     1430      +13     
  Lines       53749    54245     +496     
==========================================
+ Hits        52939    53435     +496     
  Misses        810      810              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

 10 passed

Details

 10 tests across 7 suites
 47.9 seconds
 23d07e2
 🔄 Run: #15169 (attempt 1)

[github-actions]

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

 2 passed

Details

 2 tests across 2 suites
 1 minute, 2 seconds
 23d07e2
 🔄 Run: #15169 (attempt 1)

[github-actions]

Playwright Test Results (oss - depot-ubuntu-latest-16)

 1 passed

Details

 1 test across 1 suite
 31.9 seconds
 153d917
 🔄 Run: #16914 (attempt 1)

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 41.1 seconds
 153d917
 🔄 Run: #16914 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-16)

 3 passed

Details

 3 tests across 3 suites
 50 seconds
 153d917
 🔄 Run: #16914 (attempt 1)

Playwright Test Results (oss - depot-ubuntu-latest-16)

 1 passed

Details

 1 test across 1 suite
 38.9 seconds
 4462255
 🔄 Run: #16915 (attempt 1)

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 43.5 seconds
 4462255
 🔄 Run: #16915 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-16)

 3 passed

Details

 3 tests across 3 suites
 31.7 seconds
 4462255
 🔄 Run: #16915 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 56.1 seconds
 4462255
 🔄 Run: #16915 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 1 minute, 6 seconds
 153d917
 🔄 Run: #16914 (attempt 1)

[github-actions]

Visual Regression

No baseline found — first run. Baselines will be generated after merge to main.
View full report

[khvn26]

@Holmus I'm happy to merge this once test coverage is fixed (see here), and run make generate-docs and commit the result (see failing check here).