kobotoolbox / kpi / 17162771449

push

github

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)

6900 of 10895 branches covered (63.33%)

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

26616 of 32821 relevant lines covered (81.09%)

1.6 hits per line