kobotoolbox / kpi / 17162771449

81%

master: 76%

Build Type

push

github

Committed by web-flow

Commit Message

docs(api): set up API documentation with drf-spectacular and Swagger UI (#5746)

### 📣 Summary
Integrated drf-spectacular and Swagger UI to auto-generate OpenAPI
documentation and added developer documentation to guide implementation
for each endpoint.


### 📖 Description
This PR introduces API documentation support using drf-spectacular for
OpenAPI schema generation and Swagger UI for live documentation
browsing. The setup enables automatic schema generation for KPI’s v2 API
and lays the foundation for documenting all endpoints consistently.

Enabled Swagger UI at `/api/v2/docs/` and schema access at
`/api/v2/schema/`.

Added
[README](https://github.com/kobotoolbox/kpi/blob/6d285ad83/docs/README.md)
on how to document a ViewSet properly using `@extend_schema` and related
helpers.


### 🗒️ Endpoints checklist

### Access Logs
- [x] /api/v2/access-logs/
- [x] /api/v2/access-logs/export/
- [x] /api/v2/access-logs/me/
- [x] /api/v2/access-logs/me/export/

### Asset Snapshots
- [x] /api/v2/asset_snapshots/
- [x] /api/v2/asset_snapshots/{uid}/
- [x] /api/v2/asset_snapshots/{uid}/preview/
- [x] /api/v2/asset_snapshots/{uid}/xform/
- [x] /api/v2/asset_snapshots/{uid}/xml_with_disclaimer/
   #### OpenRosa for edits
   - [x] /api/v2/asset_snapshots/{uid}/formList
   - [x] /api/v2/asset_snapshots/{uid}/manifest
   - [x] /api/v2/asset_snapshots/{uid}/submission

### Asset Subscriptions
- [x] /api/v2/asset_subscriptions/
- [x] /api/v2/asset_subscriptions/{uid}/

### Asset Usage
- [x] /api/v2/asset_usage/

### Assets
- [x] /api/v2/assets/
- [x] /api/v2/assets/{parent_lookup_asset}/counts/
- [x] /api/v2/assets/{parent_lookup_asset}/data/
- [x]
/api/v2/assets/{parent_lookup_asset}/data/{parent_lookup_data}/attachments/
- [x]
/api/v2/assets/{parent_lookup_asset}/data/{parent_lookup_data}/attachments/{pk}/
- [x]
/api/v2/assets/{parent_lookup_asset}/data/{parent_lookup_data}/attachments/{pk}/{suffix}/
- [x] /api/v2/assets/{parent_lookup_a... (continued)

Run Details

6900 of 10895 branches covered (63.33%)

2276 of 2542 new or added lines in 214 files covered. (89.54%)

19 existing lines in 5 files now uncovered.

26616 of 32821 relevant lines covered (81.09%)

1.6 hits per line