docs: improve list projects OpenAPI examples #3397
Conversation
github-actions
bot
added
docs
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughThis PR introduces Field-based metadata for ProjectBase model fields and enhances REST API documentation for the projects endpoint. Changes include adding descriptive Field definitions with examples, expanding endpoint descriptions with authentication and pagination guidance, and including comprehensive OpenAPI response examples and schemas. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
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. Comment |
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@backend/apps/api/rest/v0/project.py`:
- Around line 24-51: Replace deprecated Pydantic v1 Field(example=...) usages in
the ProjectBase schema with a v2-compatible format: update each Field for
created_at, key, level, name, and updated_at to use either examples=[...] (e.g.,
examples=["2019-09-12T20:15:45Z"]) or json_schema_extra={"example": ...} instead
of example=..., keeping the existing descriptions and types (ProjectLevel,
datetime, str) and preserving the Field(...) structure.
In `@docs/api/projects.md`:
- Line 205: Update the sentence "To fix ensure page is >= 1." in docs (the API
projects documentation) to include the missing comma so it reads "To fix, ensure
page is >= 1." — locate the exact string "To fix ensure page is >= 1." and add
the comma after "fix" to correct the grammar.
🧹 Nitpick comments (2)
docs/api/projects.md (2)
62-71: Consider using fenced code blocks for better portability.The curl examples use 2-space indentation, which may not render as code blocks in all markdown parsers (standard markdown requires 4 spaces). Using fenced code blocks with language hints would ensure consistent rendering and enable syntax highlighting.
📝 Suggested improvement
### Example request (from OpenAPI "Try it out", local dev) - curl -X 'GET' \ - 'http://localhost:8000/api/v0/projects/?level=flagship&ordering=created_at&page=1&page_size=100' \ - -H 'accept: application/json' +```bash +curl -X 'GET' \ + 'http://localhost:8000/api/v0/projects/?level=flagship&ordering=created_at&page=1&page_size=100' \ + -H 'accept: application/json' +``` In a non-local environment, you would also include the API key header: - curl -X 'GET' \ - 'https://<nest-base-url>/api/v0/projects/?level=flagship&ordering=created_at&page=1&page_size=100' \ - -H 'accept: application/json' \ - -H 'X-API-Key: YOUR_API_KEY_VALUE' +```bash +curl -X 'GET' \ + 'https://<nest-base-url>/api/v0/projects/?level=flagship&ordering=created_at&page=1&page_size=100' \ + -H 'accept: application/json' \ + -H 'X-API-Key: YOUR_API_KEY_VALUE' +```Note: The Gitleaks warning about the API key is a false positive since
YOUR_API_KEY_VALUEis clearly a placeholder.
85-107: JSON examples should use fenced code blocks.Same recommendation as above—the JSON response examples would benefit from proper fenced code blocks with
jsonlanguage hint for syntax highlighting.📝 Suggested improvement
#### Example response (truncated for brevity) Note: The items array below is intentionally truncated to keep the example readable. - { - "current_page": 1, - ... - } +```json +{ + "current_page": 1, + "has_next": true, + "has_previous": false, + "total_count": 252, + "total_pages": 3, + "items": [ + { + "created_at": "2019-09-12T20:15:45Z", + "key": "cheat-sheets", + "level": "flagship", + "name": "OWASP Cheat Sheet Series", + "updated_at": "2025-12-15T15:12:05Z" + } + ] +} +```Apply the same pattern to all other JSON examples in the file.
| created_at: datetime = Field( | ||
| ..., | ||
| description="Project creation timestamp (ISO 8601).", | ||
| example="2019-09-12T20:15:45Z", | ||
| ) | ||
| key: str = Field( | ||
| ..., | ||
| description=( | ||
| "Stable project key used as the identifier in API URLs. " | ||
| "Use this value as `{project_id}` in `GET /api/v0/projects/{project_id}`." | ||
| ), | ||
| example="cheat-sheets", | ||
| ) | ||
| level: ProjectLevel = Field( | ||
| ..., | ||
| description="Project maturity level.", | ||
| example="flagship", | ||
| ) | ||
| name: str = Field( | ||
| ..., | ||
| description="Human-readable project name.", | ||
| example="OWASP Cheat Sheet Series", | ||
| ) | ||
| updated_at: datetime = Field( | ||
| ..., | ||
| description="Last updated timestamp (ISO 8601).", | ||
| example="2025-12-15T15:12:05Z", | ||
| ) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's check the file exists and examine the code
if [ -f "backend/apps/api/rest/v0/project.py" ]; then
echo "=== File exists ==="
wc -l backend/apps/api/rest/v0/project.py
echo ""
echo "=== Lines 24-51 ==="
sed -n '24,51p' backend/apps/api/rest/v0/project.py
echo ""
echo "=== Full file structure ==="
head -60 backend/apps/api/rest/v0/project.py
else
echo "File not found"
fiRepository: OWASP/Nest
Length of output: 2723
🏁 Script executed:
# Check for version requirements
find . -type f \( -name "pyproject.toml" -o -name "requirements.txt" -o -name "requirements*.txt" -o -name "setup.py" \) | head -5 | while read f; do
echo "=== $f ==="
cat "$f" | grep -i -E "(pydantic|django-ninja|django_ninja)" || true
doneRepository: OWASP/Nest
Length of output: 244
🌐 Web query:
Pydantic v2 Field example parameter deprecated vs examples json_schema_extra
💡 Result:
Short answer:
-
Pydantic v2 does not use a Field(..., example=...) singular parameter. Use Field(..., examples=[...]) (the documented field-level parameter) or Field(..., json_schema_extra={...}) to add example(s) or other arbitrary JSON Schema keys. [1][2]
-
For deprecation: Field(..., deprecated=...) is supported in v2 — it emits a runtime DeprecationWarning when accessed and adds "deprecated": true to the generated JSON Schema (you may pass True, a string message, or a warnings.deprecated decorator). Use this to mark fields as deprecated in both runtime behavior and the JSON schema. [3][2]
References:
- json_schema_extra / examples docs. [1]
- Field parameters (examples, json_schema_extra) and JSON Schema customization. [2]
- deprecated field behavior and JSON Schema deprecation. [3]
🌐 Web query:
django-ninja 1.4.3 Pydantic v2 Field example parameter OpenAPI support
💡 Result:
Short answer: Yes — django-ninja v1.4.x is Pydantic‑v2‑aware, and OpenAPI examples come from Pydantic v2 field JSON‑schema generation. Use Pydantic v2 Field parameters (examples or json_schema_extra) to supply OpenAPI examples; django-ninja will include whatever Pydantic outputs in the generated schema.
How to do it (example):
- Preferred: use Field(..., examples=[...]) or Field(..., json_schema_extra={"example": ...}) on your Pydantic/Scheme fields. Django‑Ninja uses Pydantic’s JSON Schema for OpenAPI, so those values appear in /openapi.json and the docs UI. See Pydantic docs on field JSON‑schema customization. [1][2]
References:
- Django‑Ninja releases / v1.x Pydantic v2 migration notes. [3]
- Django‑Ninja Schema guide (shows Field usage in Schema). [4]
- Pydantic JSON Schema / Field customization (examples, json_schema_extra). [1]
If you want, I can show a minimal code snippet demonstrating Field(..., examples=[...]) and the resulting openapi fragment.
Use Pydantic v2-compatible examples or json_schema_extra instead of deprecated example parameter.
The example parameter in Field() is not supported in Pydantic v2. Since django-ninja generates OpenAPI schemas from Pydantic's JSON schema output, the examples will not appear in the OpenAPI documentation. Use either examples=[...] (list format) or json_schema_extra={"example": ...} instead:
created_at: datetime = Field(
...,
description="Project creation timestamp (ISO 8601).",
examples=["2019-09-12T20:15:45Z"],
)Or:
created_at: datetime = Field(
...,
description="Project creation timestamp (ISO 8601).",
json_schema_extra={"example": "2019-09-12T20:15:45Z"},
)Apply this fix to all Field definitions in the ProjectBase schema (lines 24-51).
🤖 Prompt for AI Agents
In `@backend/apps/api/rest/v0/project.py` around lines 24 - 51, Replace deprecated
Pydantic v1 Field(example=...) usages in the ProjectBase schema with a
v2-compatible format: update each Field for created_at, key, level, name, and
updated_at to use either examples=[...] (e.g.,
examples=["2019-09-12T20:15:45Z"]) or json_schema_extra={"example": ...} instead
of example=..., keeping the existing descriptions and types (ProjectLevel,
datetime, str) and preserving the Field(...) structure.
| ] | ||
| } | ||
|
|
||
| To fix ensure page is >= 1. |
There was a problem hiding this comment.
Minor grammar fix: missing comma.
📝 Suggested fix
-To fix ensure page is >= 1.
+To fix, ensure page is >= 1.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| To fix ensure page is >= 1. | |
| To fix, ensure page is >= 1. |
🤖 Prompt for AI Agents
In `@docs/api/projects.md` at line 205, Update the sentence "To fix ensure page is
>= 1." in docs (the API projects documentation) to include the missing comma so
it reads "To fix, ensure page is >= 1." — locate the exact string "To fix ensure
page is >= 1." and add the comma after "fix" to correct the grammar.
|
docs/api/projects.md wasn't / isn't meant to be included in the PR. Didn't realize it was still being picked up |
1 participant
Proposed change
Resolves #3062
References #3062
Update the Swagger/OpenAPI docs for the List Projects endpoint to include clearer response details and examples in the backend API schema.
Checklist
make check-testlocally: all warnings addressed, tests passedTesting
make check-test(fails in frontend unit tests with jest timeout/act warnings and a SIGKILL during parallel runs)docker run --env-file frontend/.env.example --rm nest-test-frontend-unit sh -lc "pnpm exec tsc --noEmit && NODE_OPTIONS='--experimental-vm-modules --no-warnings=DEP0040' pnpm exec jest --runInBand --testTimeout=20000"(pass).Ran Jest in-band with a higher timeout to avoid parallel-run timeouts and stabilize the frontend unit suite locally; this completed successfully.