docs: auto-generate API route documentation

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: Id0d1f9769b7ccdbf83d5fa78adef62e46a6a6964

docs/api/shares.md

@@ -0,0 +1,282 @@
+# Shares
+
+Media sharing and notifications
+
+## Endpoints
+
+### GET /api/v1/notifications/shares
+
+Get unread share notifications
+GET /api/notifications/shares
+
+**Authentication:** Required (Bearer JWT)
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Unread notifications |
+| 401 | Unauthorized |
+
+---
+
+### POST /api/v1/notifications/shares/read-all
+
+Mark all notifications as read
+POST /api/notifications/shares/read-all
+
+**Authentication:** Required (Bearer JWT)
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | All notifications marked as read |
+| 401 | Unauthorized |
+
+---
+
+### POST /api/v1/notifications/shares/{id}/read
+
+Mark a notification as read
+POST /api/notifications/shares/{id}/read
+
+**Authentication:** Required (Bearer JWT)
+
+#### Parameters
+
+| Name | In | Required | Description |
+|------|----|----------|-------------|
+| `id` | path | Yes | Notification ID |
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Notification marked as read |
+| 401 | Unauthorized |
+
+---
+
+### GET /api/v1/shared/{token}
+
+Access a public shared resource
+GET /api/shared/{token}
+
+**Authentication:** Required (Bearer JWT)
+
+#### Parameters
+
+| Name | In | Required | Description |
+|------|----|----------|-------------|
+| `token` | path | Yes | Share token |
+| `password` | query | No | Share password if required |
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Shared content |
+| 401 | Unauthorized |
+| 404 | Not found |
+
+---
+
+### POST /api/v1/shares
+
+Create a new share
+POST /api/shares
+
+**Authentication:** Required (Bearer JWT)
+
+#### Request Body
+
+`Content-Type: application/json`
+
+See `docs/api/openapi.json` for the full schema.
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Share created |
+| 400 | Bad request |
+| 401 | Unauthorized |
+| 500 | Internal server error |
+
+---
+
+### POST /api/v1/shares/batch/delete
+
+Batch delete shares
+POST /api/shares/batch/delete
+
+**Authentication:** Required (Bearer JWT)
+
+#### Request Body
+
+`Content-Type: application/json`
+
+See `docs/api/openapi.json` for the full schema.
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Shares deleted |
+| 400 | Bad request |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+
+---
+
+### GET /api/v1/shares/incoming
+
+List incoming shares (shares shared with me)
+GET /api/shares/incoming
+
+**Authentication:** Required (Bearer JWT)
+
+#### Parameters
+
+| Name | In | Required | Description |
+|------|----|----------|-------------|
+| `offset` | query | No | Pagination offset |
+| `limit` | query | No | Pagination limit |
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Incoming shares |
+| 401 | Unauthorized |
+
+---
+
+### GET /api/v1/shares/outgoing
+
+List outgoing shares (shares I created)
+GET /api/shares/outgoing
+
+**Authentication:** Required (Bearer JWT)
+
+#### Parameters
+
+| Name | In | Required | Description |
+|------|----|----------|-------------|
+| `offset` | query | No | Pagination offset |
+| `limit` | query | No | Pagination limit |
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Outgoing shares |
+| 401 | Unauthorized |
+
+---
+
+### GET /api/v1/shares/{id}
+
+Get share details
+GET /api/shares/{id}
+
+**Authentication:** Required (Bearer JWT)
+
+#### Parameters
+
+| Name | In | Required | Description |
+|------|----|----------|-------------|
+| `id` | path | Yes | Share ID |
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Share details |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not found |
+
+---
+
+### PATCH /api/v1/shares/{id}
+
+Update a share
+PATCH /api/shares/{id}
+
+**Authentication:** Required (Bearer JWT)
+
+#### Parameters
+
+| Name | In | Required | Description |
+|------|----|----------|-------------|
+| `id` | path | Yes | Share ID |
+
+#### Request Body
+
+`Content-Type: application/json`
+
+See `docs/api/openapi.json` for the full schema.
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Share updated |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not found |
+
+---
+
+### DELETE /api/v1/shares/{id}
+
+Delete (revoke) a share
+DELETE /api/shares/{id}
+
+**Authentication:** Required (Bearer JWT)
+
+#### Parameters
+
+| Name | In | Required | Description |
+|------|----|----------|-------------|
+| `id` | path | Yes | Share ID |
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 204 | Share deleted |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not found |
+
+---
+
+### GET /api/v1/shares/{id}/activity
+
+Get share activity log
+GET /api/shares/{id}/activity
+
+**Authentication:** Required (Bearer JWT)
+
+#### Parameters
+
+| Name | In | Required | Description |
+|------|----|----------|-------------|
+| `id` | path | Yes | Share ID |
+| `offset` | query | No | Pagination offset |
+| `limit` | query | No | Pagination limit |
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Share activity |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not found |
+
+---
+