Flagsmith / Flagsmith/flagsmith
API: OpenAPI schema does not match live responses (breaks strict output validation)
- Dominant language
- Python
- Stars
- 6.6k
- Forks
- 567
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 121
Description
The published OpenAPI schema (`/api/v1/swagger.json`) disagrees with actual API responses in several systematic ways. Any client that validates responses against the schema (e.g. the Flagsmith MCP server, which uses FastMCP's `from_openapi` output validation) fails on most endpoints. Found by crawling the MCP-tagged read endpoints against SaaS and validating each response against its declared schema.
### 1. Pagination `next`/`previous` typed `string`, returned `null`
Paginated responses declare `next` and `previous` as non-nullable `string`, but the API returns `null` when there is no adjacent page. Should be `string, nullable` (`anyOf: [string, "null"]`).
Affected: `list_organizations`, `list_organization_groups`, `list_organization_invites`, `list_organization_roles`, `list_environments`, `list_project_features`, `list_project_segments`, `list_project_change_requests`, `list_feature_multivariate_options`, `list_feature_segments`, `get_environment_feature_versions` (likely all paginated list endpoints).
### 2. Array-returning endpoints declared as a single object
The 200 response schema is the singular item serializer, but the endpoint returns a JSON array. Should be `type: array, items: `.
- `GET /organisations/{id}/projects/` (list_projects_in_organization)
- `GET /projects/{id}/environments/` (list_project_environments)
- `GET /projects/{project_pk}/features/{feature_pk}/code-references/`
- `GET /projects/{project_pk}/features/{id}/evaluation-data/`
### 3. `get_feature_external_resources`: missing `count`
`GET …/feature-external-resources/` returns `{"results": []}` but the schema marks `count` as required. Either the response should include the full pagination envelope or the schema should not require `count`.
### 4. `owners` / `group_owners` typed as integer IDs but expanded in responses
Read responses expand these to nested user objects (`{id,email,first_name,last_name,last_login,uuid}`), while the schema types them as `array`. Affects `get_feature_flag` and `list_project_features` (`results[].owners[]`); likely anywhere a feature is serialised for read.
### Impact / workaround
The MCP server currently sets `validate_output=False` to avoid rejecting valid responses. We'd like to re-enable output validation once the schema matches reality.
Contributor guide
Assessment
This issue has not been assessed yet.