kobotoolbox / kpi / 17162771449 / 1

82%

master: 76%

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)

6714 of 10944 branches covered (61.35%)

25856 of 32821 relevant lines covered (78.78%)

0.79 hits per line