docs: auto-generate API route documentation
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: Id0d1f9769b7ccdbf83d5fa78adef62e46a6a6964
This commit is contained in:
parent
9d58927cb4
commit
934691c0f9
GPG key ID:
29D95B64378DB4BF
40 changed files with 17444 additions and 1 deletions
412
docs/api/sync.md
Normal file
412
docs/api/sync.md
Normal file
|
|
@ -0,0 +1,412 @@
|
|||
# Sync
|
||||
|
||||
Multi-device library synchronization
|
||||
|
||||
## Endpoints
|
||||
|
||||
### POST /api/v1/sync/ack
|
||||
|
||||
Acknowledge processed changes
|
||||
POST /api/sync/ack
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Request Body
|
||||
|
||||
`Content-Type: application/json`
|
||||
|
||||
See `docs/api/openapi.json` for the full schema.
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Changes acknowledged |
|
||||
| 400 | Bad request |
|
||||
| 401 | Unauthorized |
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/sync/changes
|
||||
|
||||
Get changes since cursor
|
||||
GET /api/sync/changes
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `cursor` | query | No | Sync cursor |
|
||||
| `limit` | query | No | Max changes (max 1000) |
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Changes since cursor |
|
||||
| 400 | Bad request |
|
||||
| 401 | Unauthorized |
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/sync/conflicts
|
||||
|
||||
List unresolved conflicts
|
||||
GET /api/sync/conflicts
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Unresolved conflicts |
|
||||
| 401 | Unauthorized |
|
||||
|
||||
---
|
||||
|
||||
### POST /api/v1/sync/conflicts/{id}/resolve
|
||||
|
||||
Resolve a sync conflict
|
||||
POST /api/sync/conflicts/{id}/resolve
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `id` | path | Yes | Conflict ID |
|
||||
|
||||
#### Request Body
|
||||
|
||||
`Content-Type: application/json`
|
||||
|
||||
See `docs/api/openapi.json` for the full schema.
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Conflict resolved |
|
||||
| 400 | Bad request |
|
||||
| 401 | Unauthorized |
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/sync/devices
|
||||
|
||||
List user's sync devices
|
||||
GET /api/sync/devices
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | List of devices |
|
||||
| 401 | Unauthorized |
|
||||
|
||||
---
|
||||
|
||||
### POST /api/v1/sync/devices
|
||||
|
||||
Register a new sync device
|
||||
POST /api/sync/devices
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Request Body
|
||||
|
||||
`Content-Type: application/json`
|
||||
|
||||
See `docs/api/openapi.json` for the full schema.
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Device registered |
|
||||
| 400 | Bad request |
|
||||
| 401 | Unauthorized |
|
||||
| 500 | Internal server error |
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/sync/devices/{id}
|
||||
|
||||
Get device details
|
||||
GET /api/sync/devices/{id}
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `id` | path | Yes | Device ID |
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Device details |
|
||||
| 401 | Unauthorized |
|
||||
| 403 | Forbidden |
|
||||
| 404 | Not found |
|
||||
|
||||
---
|
||||
|
||||
### PUT /api/v1/sync/devices/{id}
|
||||
|
||||
Update a device
|
||||
PUT /api/sync/devices/{id}
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `id` | path | Yes | Device ID |
|
||||
|
||||
#### Request Body
|
||||
|
||||
`Content-Type: application/json`
|
||||
|
||||
See `docs/api/openapi.json` for the full schema.
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Device updated |
|
||||
| 401 | Unauthorized |
|
||||
| 403 | Forbidden |
|
||||
| 404 | Not found |
|
||||
|
||||
---
|
||||
|
||||
### DELETE /api/v1/sync/devices/{id}
|
||||
|
||||
Delete a device
|
||||
DELETE /api/sync/devices/{id}
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `id` | path | Yes | Device ID |
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 204 | Device deleted |
|
||||
| 401 | Unauthorized |
|
||||
| 403 | Forbidden |
|
||||
| 404 | Not found |
|
||||
|
||||
---
|
||||
|
||||
### POST /api/v1/sync/devices/{id}/token
|
||||
|
||||
Regenerate device token
|
||||
POST /api/sync/devices/{id}/token
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `id` | path | Yes | Device ID |
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Token regenerated |
|
||||
| 401 | Unauthorized |
|
||||
| 403 | Forbidden |
|
||||
| 404 | Not found |
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/sync/download/{path}
|
||||
|
||||
Download a file for sync (supports Range header)
|
||||
GET /api/sync/download/{*path}
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `path` | path | Yes | File path |
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | File content |
|
||||
| 206 | Partial content |
|
||||
| 401 | Unauthorized |
|
||||
| 404 | Not found |
|
||||
|
||||
---
|
||||
|
||||
### POST /api/v1/sync/report
|
||||
|
||||
Report local changes from client
|
||||
POST /api/sync/report
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Request Body
|
||||
|
||||
`Content-Type: application/json`
|
||||
|
||||
See `docs/api/openapi.json` for the full schema.
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Changes processed |
|
||||
| 400 | Bad request |
|
||||
| 401 | Unauthorized |
|
||||
|
||||
---
|
||||
|
||||
### POST /api/v1/sync/upload
|
||||
|
||||
Create an upload session for chunked upload
|
||||
POST /api/sync/upload
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Request Body
|
||||
|
||||
`Content-Type: application/json`
|
||||
|
||||
See `docs/api/openapi.json` for the full schema.
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Upload session created |
|
||||
| 400 | Bad request |
|
||||
| 401 | Unauthorized |
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/sync/upload/{id}
|
||||
|
||||
Get upload session status
|
||||
GET /api/sync/upload/{id}
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `id` | path | Yes | Upload session ID |
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Upload session status |
|
||||
| 401 | Unauthorized |
|
||||
| 404 | Not found |
|
||||
|
||||
---
|
||||
|
||||
### DELETE /api/v1/sync/upload/{id}
|
||||
|
||||
Cancel an upload session
|
||||
DELETE /api/sync/upload/{id}
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `id` | path | Yes | Upload session ID |
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 204 | Upload cancelled |
|
||||
| 401 | Unauthorized |
|
||||
| 404 | Not found |
|
||||
|
||||
---
|
||||
|
||||
### PUT /api/v1/sync/upload/{id}/chunks/{index}
|
||||
|
||||
Upload a chunk
|
||||
PUT /api/sync/upload/{id}/chunks/{index}
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `id` | path | Yes | Upload session ID |
|
||||
| `index` | path | Yes | Chunk index |
|
||||
|
||||
#### Request Body
|
||||
|
||||
Chunk binary data
|
||||
`Content-Type: application/octet-stream`
|
||||
|
||||
See `docs/api/openapi.json` for the full schema.
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Chunk received |
|
||||
| 400 | Bad request |
|
||||
| 401 | Unauthorized |
|
||||
| 404 | Not found |
|
||||
|
||||
---
|
||||
|
||||
### POST /api/v1/sync/upload/{id}/complete
|
||||
|
||||
Complete an upload session
|
||||
POST /api/sync/upload/{id}/complete
|
||||
|
||||
**Authentication:** Required (Bearer JWT)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Required | Description |
|
||||
|------|----|----------|-------------|
|
||||
| `id` | path | Yes | Upload session ID |
|
||||
|
||||
#### Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| 200 | Upload completed |
|
||||
| 400 | Bad request |
|
||||
| 401 | Unauthorized |
|
||||
| 404 | Not found |
|
||||
|
||||
---
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue