feat(api-docs): Generate OpenAPI 3.1 docs with drf-spectacular

[khvn26]

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

• 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

Contributes to #6183.

In this PR, we switch from drf-yasg to drf-spectacular for the OpenAPI/Swagger generation. This enables us to use anyOf, oneOf and type: str[] to express union type fields.

Additionally, I've added an sdk tag to distinguish the SDK endpoints from the management ones.

How did you test this code?

1. Made sure the tests pass.
2. Observed http://127.0.0.1:8000/api/v1/docs/# and took note of appropriately generated union type fields — e.g. at $.components.schemas.TraitModel.properties.trait_value.
3. Installed openapi-generator and ran openapi-generator generate -i http://localhost:8000/api/v1/swagger.json\?format\=json -g typescript.

[vercel]

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

3 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
docs	Ignored	Preview	Jan 7, 2026 2:27pm
flagsmith-frontend-preview	Ignored	Preview	Jan 7, 2026 2:27pm
flagsmith-frontend-staging	Ignored	Preview	Jan 7, 2026 2:27pm

[github-actions]

Docker builds report

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.08%. Comparing base (7dfc785) to head (1e9902e).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6451      +/-   ##
==========================================
+ Coverage   98.07%   98.08%   +0.01%     
==========================================
  Files        1294     1296       +2     
  Lines       46537    46616      +79     
==========================================
+ Hits        45639    45724      +85     
+ Misses        898      892       -6     

☔ 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.

[khvn26]

@Zaimwa9 Yeah, looks like the typing and test coverage sections went over Claude's head here.

[khvn26]

When adding new tests to fix coverage (33ba2ee), Claude followed the test naming template documented here.

CC @Zaimwa9 @emyller

[Zaimwa9]

flagsmith/api/edge_api/identities/serializers.py

Lines 167 to 168 in 33ba2ee

	class Meta:
	swagger_schema_fields = {"type": "integer/string"}

I believe this type hack needs to be turned into a anyOf too

I started on it the other day and ended up using OpenApiSerializerFieldExtension to map these custom fields to proper anyOf schema.

Like this if it can help:

  class EdgeFeatureFieldExtension(OpenApiSerializerFieldExtension):
      target_class = "edge_api.identities.serializers.EdgeFeatureField"

      def map_serializer_field(self, auto_schema, direction):
          if direction == "request":
              return {
                  "anyOf": [
                      {"type": "integer", "description": "Feature ID"},
                      {"type": "string", "description": "Feature name"},
                  ],
              }
          return {"type": "integer"}

  Same for FeatureStateValueEdgeIdentityField which accepts int | str | bool.

---

But overall looks good. I was moving on comparing with prod schemas, I ran it against your branch, here is the output if it can be of any help:

 | Metric             | Production | This PR |
  |--------------------|------------|---------|
  | OpenAPI Version    | 2.0        | 3.0.3   |
  | Endpoints          | 524        | 509     |
  | Schemas            | 257        | 373     |
  | Schemas with anyOf | 0          | 8       |

  Critical fields still missing anyOf:

  | Field               | Production             | This PR        | Expected                |
  |---------------------|------------------------|----------------|-------------------------|
  | feature             | type: "integer/string" | type: "string" | anyOf: [int, str]       |
  | feature_state_value | type: "string"         | type: "string" | anyOf: [int, str, bool] |

The 8 schemas with anyOf are all Pydantic models (e.g., TraitModel). The DRF serializer fields (EdgeFeatureField, FeatureStateValueEdgeIdentityField) need explicit OpenApiSerializerFieldExtension classes.

  Missing endpoints (16) - all expected:
  - SAML (14) - enterprise SSO
  - Licence (1) - enterprise
  - Onboarding (1) - renamed

[matthewelwell]

I've given this a fairly surface review but LGTM.

Secured Wadii's approval offline.