Docs (openapi): enrich /docs — metadata, Authorize button, param + error docs#4
Docs (openapi): enrich /docs — metadata, Authorize button, param + error docs#4sagargg wants to merge 4 commits into
Conversation
…ror docs The interactive docs were running on FastAPI defaults. This fills them in: App metadata: title, version (from package metadata), summary, a markdown description (envelope shape, auth model, streaming/pagination), tag descriptions, and contact — so the /docs landing page is no longer bare. Security: declare the `Authorization` header as an APIKeyHeader security scheme instead of a raw Header param. Swagger now shows an 'Authorize' button (set the token once) and the header stops leaking as a parameter on every operation. Params + examples: every request field gets a description; query params on datastore_search (filters/q/sort/fields/…) are documented; create/upsert/delete bodies carry worked examples so 'Try it out' is pre-filled. Errors: add an ErrorEnvelope model and attach the real CKAN 4xx/5xx envelope (400/403/404/409/500) to every action via a shared ERROR_RESPONSES; document /ready's 503 and dump's 302; strip FastAPI's misleading auto-422 (validation errors are remapped to a 400 envelope). Human operation summaries replace the machine-derived ones (e.g. 'Datastore Search Sql'). Also: set a dummy CKAN_URL in conftest so `create_app()` builds under the default ckan auth in CI (same import-time fix as the schema-in-OPTIONS PR; harmless when both land). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 52 minutes and 59 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. 📝 WalkthroughWalkthroughThis PR consolidates API documentation into a dedicated reference file, enhances request/response schemas with OpenAPI metadata, and upgrades FastAPI endpoint decorators and OpenAPI configuration to provide versioning, error response mappings, and security scheme documentation. ChangesOpenAPI & API Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 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 |
Recapitalise the Swagger tag groups (Health / Datastore / Datastore Download, Health first), move datastore_delete up next to create/upsert, trim the app description, and point contact at datopian.com.
- Rewrite README to a minimal overview (quick start, config essentials, doc links). - Add API.md — full per-endpoint HTTP reference (envelope, auth, errors, examples, Postman link). - Replace CLAUDE.md's request/response contracts section with a pointer to API.md (~951 -> ~540 lines). - Improve the Swagger operation summaries on datastore_search / datastore_search_sql / dump.
![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
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@API.md`:
- Around line 269-275: The two unlabeled fenced code blocks showing example HTTP
requests (the block beginning with "GET /api/3/action/datastore_search
?resource_id=balancing_auction_results_2025 ..." and the block beginning with
"GET /api/3/action/datastore_search_sql?sql= SELECT product_code, AVG(...") must
be given a language tag to satisfy markdownlint MD040; edit those fences to use
a language label such as ```http (or ```text) instead of bare ``` so both
example blocks are explicitly tagged.
In `@datastore/main.py`:
- Around line 130-132: The summary string contains a typo ("Datasore"); update
the summary value used (the summary parameter in the object or function where
it's defined) to read "A Datastore API endpoint for managing tabular data
resources." so the word "Datastore" is spelled correctly; locate the summary
parameter in datatore/main.py and correct the string literal accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 003c59f8-6644-485a-8b4b-ac9f07fded1c
📒 Files selected for processing (12)
API.mdCLAUDE.mdREADME.mddatastore/api/context.pydatastore/api/endpoints/datastore.pydatastore/api/endpoints/dump.pydatastore/api/endpoints/health.pydatastore/api/responses.pydatastore/main.pydatastore/schemas/request.pydatastore/schemas/responses.pytests/conftest.py
| ``` | ||
| GET /api/3/action/datastore_search | ||
| ?resource_id=balancing_auction_results_2025 | ||
| &filters={"product_code":"DCL","accepted":true} | ||
| &sort=delivery_start desc | ||
| &limit=100 | ||
| ``` |
There was a problem hiding this comment.
Add language tags to fenced examples to satisfy markdownlint.
Line 269 and Line 318 use unlabeled code fences; this triggers MD040. Use a language tag (for example, http or text) on both blocks.
Suggested patch
-```
+```http
GET /api/3/action/datastore_search
?resource_id=balancing_auction_results_2025
&filters={"product_code":"DCL","accepted":true}
&sort=delivery_start desc
&limit=100@@
- +http
GET /api/3/action/datastore_search_sql?sql=
SELECT product_code, AVG(clearing_price_gbp_per_mwh) AS avg_price
FROM "balancing_auction_results_2025"
WHERE accepted = true
GROUP BY product_code
LIMIT 1000
Also applies to: 318-325
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 269-269: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@API.md` around lines 269 - 275, The two unlabeled fenced code blocks showing
example HTTP requests (the block beginning with "GET
/api/3/action/datastore_search ?resource_id=balancing_auction_results_2025 ..."
and the block beginning with "GET /api/3/action/datastore_search_sql?sql= SELECT
product_code, AVG(...") must be given a language tag to satisfy markdownlint
MD040; edit those fences to use a language label such as ```http (or ```text)
instead of bare ``` so both example blocks are explicitly tagged.
| summary=( | ||
| "A Datasore API endpoint for managing tabular data resources. " | ||
| ), |
There was a problem hiding this comment.
Fix typo in summary text.
Line 131 has "Datasore" instead of "Datastore".
📝 Proposed fix
summary=(
- "A Datasore API endpoint for managing tabular data resources. "
+ "A Datastore API endpoint for managing tabular data resources. "
),📝 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.
| summary=( | |
| "A Datasore API endpoint for managing tabular data resources. " | |
| ), | |
| summary=( | |
| "A Datastore API endpoint for managing tabular data resources. " | |
| ), |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@datastore/main.py` around lines 130 - 132, The summary string contains a typo
("Datasore"); update the summary value used (the summary parameter in the object
or function where it's defined) to read "A Datastore API endpoint for managing
tabular data resources." so the word "Datastore" is spelled correctly; locate
the summary parameter in datatore/main.py and correct the string literal
accordingly.
1 participant
The interactive docs at
/docswere running almost entirely on FastAPI defaults (onlytitle+version). This fills them in across three areas — no behavioral change to the API itself.App metadata
title,version(read from package metadata so it tracks releases),summary, a markdowndescription(envelope shape, auth model, streaming + pagination), per-tag descriptions (datastore/health/dump), andcontact. The/docslanding area is no longer empty.Security
The
Authorizationheader is now declared as anAPIKeyHeadersecurity scheme instead of a rawHeaderparameter. Swagger renders an Authorize button (set the token once for every call), and the header stops leaking as a parameter on each operation.Params + examples
description.datastore_searchquery params (filters,q,sort,fields,records_format, …) are documented — previously all undocumented.datastore_create/upsert/deletebodies carry worked examples, so Try it out is pre-filled with a valid body.Errors
ErrorEnvelopemodel + a sharedERROR_RESPONSES, attached at router level so every action documents the real CKAN 4xx/5xx shape (400/403/404/409/500)./ready's 503 and the dump endpoint's 302 are documented.422is stripped (validation errors are remapped to a 400 CKAN envelope, so a 422 never actually occurs).Testing
pytest: 320 passing (CI-equivalent env);ruff: clean; no net-newmypyerrors./openapi.jsonwas verified: 12/12 search params described, security scheme present,Authorizationno longer a param, no422anywhere, error codes + 503/302 present.Note
Includes the same one-line
conftestCKAN_URLfix as #3 (needed socreate_app()builds under the defaultckanauth in CI, where there's no.env). It's identical to #3's, so whichever merges second is a no-op — these two PRs touch otherwise-disjoint files.🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
API & OpenAPI Improvements