Summary
The Pydantic models that define the API contract currently provide little or no field-level documentation. Most model attributes lack Field() metadata such as descriptions, examples, and validation constraints, resulting in an OpenAPI schema that exposes only field names without explaining their purpose.
Enhancing the models with descriptive metadata will make the generated API documentation significantly more informative and improve the developer experience for API consumers.
Location
- File:
backend/app/models.py
Affected Models (Examples)
FindingScanResponseFixVerifyResponse
Other public request and response models should also be reviewed for consistency.
Current Behavior
Many model fields are declared without accompanying metadata.
For example:
class Finding(BaseModel):
metadata: dict
features: list
reachability: strIn the generated OpenAPI schema, consumers only see the field names and types, with no explanation of:
- What the field represents.
- Whether it is required or optional.
- Expected values or formats.
- Example payloads.
Fields with generic names such as metadata, features, and reachability are particularly difficult to interpret without consulting the implementation.
Why This Is a Problem
FastAPI automatically generates API documentation from Pydantic models. Without descriptive field metadata:
- Developers must inspect the source code to understand response objects.
- Generic field names become ambiguous.
- API integrations become more error-prone.
- Generated client SDKs lack meaningful documentation.
- The OpenAPI schema provides limited value beyond type information.
Expected Behavior
All public request and response models should include descriptive metadata for their fields.
Where appropriate, fields should define:
- A human-readable description.
- Example values.
- Validation constraints.
- Default values (if applicable).
This ensures the generated OpenAPI schema clearly communicates the API contract.
Proposed Solution
Annotate model fields using Field().
Example:
from pydantic import BaseModel, Field
class Finding(BaseModel):
severity: str = Field(
description="Severity level assigned to the finding.",
examples=["high"],
)
reachability: str = Field(
description="Indicates whether the vulnerable code path is reachable.",
examples=["reachable"],
)
metadata: dict = Field(
description="Scanner-specific metadata associated with the finding.",
examples=[{"rule": "hardcoded-secret"}],
)Additionally:
- Provide examples for nested models.
- Add validation constraints where appropriate (e.g.,
min_length, max_length, ge, le, regex patterns).
- Review all public API models for consistency.
Acceptance Criteria
Impact
- Type: Documentation Enhancement
- Component: Backend Models
- Difficulty: Low
- Severity: Low
Additional Notes
FastAPI leverages Pydantic metadata to generate rich OpenAPI documentation automatically. Adding field-level descriptions and examples requires minimal implementation effort while greatly improving API usability, generated client SDKs, and overall developer experience.
Summary
The Pydantic models that define the API contract currently provide little or no field-level documentation. Most model attributes lack
Field()metadata such as descriptions, examples, and validation constraints, resulting in an OpenAPI schema that exposes only field names without explaining their purpose.Enhancing the models with descriptive metadata will make the generated API documentation significantly more informative and improve the developer experience for API consumers.
Location
backend/app/models.pyAffected Models (Examples)
FindingScanResponseFixVerifyResponseCurrent Behavior
Many model fields are declared without accompanying metadata.
For example:
In the generated OpenAPI schema, consumers only see the field names and types, with no explanation of:
Fields with generic names such as
metadata,features, andreachabilityare particularly difficult to interpret without consulting the implementation.Why This Is a Problem
FastAPI automatically generates API documentation from Pydantic models. Without descriptive field metadata:
Expected Behavior
All public request and response models should include descriptive metadata for their fields.
Where appropriate, fields should define:
This ensures the generated OpenAPI schema clearly communicates the API contract.
Proposed Solution
Annotate model fields using
Field().Example:
Additionally:
min_length,max_length,ge,le, regex patterns).Acceptance Criteria
Field()metadata for all exposed fields.Impact
Additional Notes
FastAPI leverages Pydantic metadata to generate rich OpenAPI documentation automatically. Adding field-level descriptions and examples requires minimal implementation effort while greatly improving API usability, generated client SDKs, and overall developer experience.