Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
Add OpenAPI documentation and Swagger UI at /api/v1/docs
Murtaza Nasiread0c0a074ed
diff --git a/src/api/api_v1.py b/src/api/api_v1.pyindex 201b2c9f..07208dbf 100644--- a/src/api/api_v1.py+++ b/src/api/api_v1.py@@ -70,6 +70,239 @@ def format_bytes(bytes_value: int) -> str:return f"{bytes_value:.1f} PB"+# =============================================================================+# OpenAPI Documentation+# =============================================================================++OPENAPI_SPEC = {+ "openapi": "3.0.3",+ "info": {+ "title": "Speakr API v1",+ "description": "REST API for Speakr - Audio transcription and note-taking application.\n\n## Authentication\nAll endpoints require token authentication via one of:\n- `Authorization: Bearer <token>`\n- `X-API-Token: <token>`\n- `API-Token: <token>`\n- `?token=<token>` query parameter\n\nGenerate tokens in Settings > API Tokens.",+ "version": "1.0.0"+ },+ "servers": [{"url": "/api/v1", "description": "API v1"}],+ "components": {+ "securitySchemes": {+ "bearerAuth": {"type": "http", "scheme": "bearer"},+ "apiKeyHeader": {"type": "apiKey", "in": "header", "name": "X-API-Token"},+ "apiKeyQuery": {"type": "apiKey", "in": "query", "name": "token"}+ },+ "schemas": {+ "Recording": {+ "type": "object",+ "properties": {+ "id": {"type": "integer"},+ "title": {"type": "string"},+ "status": {"type": "string", "enum": ["PENDING", "PROCESSING", "SUMMARIZING", "COMPLETED", "FAILED"]},+ "created_at": {"type": "string", "format": "date-time"},+ "meeting_date": {"type": "string", "format": "date-time"},+ "file_size": {"type": "integer"},+ "participants": {"type": "string"},+ "is_inbox": {"type": "boolean"},+ "is_highlighted": {"type": "boolean"},+ "tags": {"type": "array", "items": {"$ref": "#/components/schemas/Tag"}}+ }+ },+ "Tag": {+ "type": "object",+ "properties": {+ "id": {"type": "integer"},+ "name": {"type": "string"},+ "color": {"type": "string"},+ "custom_prompt": {"type": "string"},+ "default_language": {"type": "string"},+ "default_min_speakers": {"type": "integer"},+ "default_max_speakers": {"type": "integer"}+ }+ },+ "Speaker": {+ "type": "object",+ "properties": {+ "id": {"type": "integer"},+ "name": {"type": "string"},+ "use_count": {"type": "integer"},+ "has_voice_profile": {"type": "boolean"}+ }+ },+ "Error": {+ "type": "object",+ "properties": {"error": {"type": "string"}}+ }+ }+ },+ "security": [{"bearerAuth": []}, {"apiKeyHeader": []}, {"apiKeyQuery": []}],+ "paths": {+ "/stats": {+ "get": {+ "tags": ["Stats"],+ "summary": "Get system statistics",+ "description": "Returns stats compatible with gethomepage.dev widgets",+ "parameters": [{"name": "scope", "in": "query", "schema": {"type": "string", "enum": ["user", "all"], "default": "user"}, "description": "user=personal stats, all=global (admin only)"}],+ "responses": {"200": {"description": "Stats object"}}+ }+ },+ "/recordings": {+ "get": {+ "tags": ["Recordings"],+ "summary": "List recordings",+ "parameters": [+ {"name": "page", "in": "query", "schema": {"type": "integer", "default": 1}},+ {"name": "per_page", "in": "query", "schema": {"type": "integer", "default": 25, "maximum": 100}},+ {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["all", "pending", "processing", "completed", "failed"]}},+ {"name": "sort_by", "in": "query", "schema": {"type": "string", "enum": ["created_at", "meeting_date", "title", "file_size"]}},+ {"name": "sort_order", "in": "query", "schema": {"type": "string", "enum": ["asc", "desc"]}},+ {"name": "tag_id", "in": "query", "schema": {"type": "integer"}},+ {"name": "q", "in": "query", "schema": {"type": "string"}, "description": "Search query"}+ ],+ "responses": {"200": {"description": "Paginated list of recordings"}}+ }+ },+ "/recordings/{id}": {+ "get": {+ "tags": ["Recordings"],+ "summary": "Get recording details",+ "parameters": [+ {"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}},+ {"name": "format", "in": "query", "schema": {"type": "string", "enum": ["full", "minimal"]}, "description": "minimal excludes large text fields"},+ {"name": "include", "in": "query", "schema": {"type": "string"}, "description": "Comma-separated: transcription,summary,notes"}+ ],+ "responses": {"200": {"description": "Recording details"}, "404": {"description": "Not found"}}+ },+ "patch": {+ "tags": ["Recordings"],+ "summary": "Update recording",+ "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],+ "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string"}, "participants": {"type": "string"}, "notes": {"type": "string"}, "summary": {"type": "string"}, "meeting_date": {"type": "string"}, "is_inbox": {"type": "boolean"}, "is_highlighted": {"type": "boolean"}}}}}},+ "responses": {"200": {"description": "Updated recording"}}+ },+ "delete": {+ "tags": ["Recordings"],+ "summary": "Delete recording",+ "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],+ "responses": {"200": {"description": "Deleted"}, "403": {"description": "Permission denied"}}+ }+ },+ "/recordings/{id}/transcript": {+ "get": {+ "tags": ["Recordings"],+ "summary": "Get transcript",+ "parameters": [+ {"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}},+ {"name": "format", "in": "query", "schema": {"type": "string", "enum": ["json", "text", "srt", "vtt"], "default": "json"}}+ ],+ "responses": {"200": {"description": "Transcript in requested format"}}+ }+ },+ "/recordings/{id}/summary": {+ "get": {"tags": ["Recordings"], "summary": "Get summary", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Summary markdown"}}},+ "put": {"tags": ["Recordings"], "summary": "Replace summary", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["summary"], "properties": {"summary": {"type": "string"}}}}}}, "responses": {"200": {"description": "Updated"}}}+ },+ "/recordings/{id}/notes": {+ "get": {"tags": ["Recordings"], "summary": "Get notes", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Notes markdown"}}},+ "put": {"tags": ["Recordings"], "summary": "Replace notes", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["notes"], "properties": {"notes": {"type": "string"}}}}}}, "responses": {"200": {"description": "Updated"}}}+ },+ "/recordings/{id}/status": {+ "get": {"tags": ["Recordings"], "summary": "Get processing status", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Status with queue position"}}}+ },+ "/recordings/{id}/transcribe": {+ "post": {"tags": ["Processing"], "summary": "Queue transcription", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"language": {"type": "string"}, "min_speakers": {"type": "integer"}, "max_speakers": {"type": "integer"}}}}}}, "responses": {"200": {"description": "Job queued"}}}+ },+ "/recordings/{id}/summarize": {+ "post": {"tags": ["Processing"], "summary": "Queue summarization", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"custom_prompt": {"type": "string"}}}}}}, "responses": {"200": {"description": "Job queued"}}}+ },+ "/recordings/{id}/chat": {+ "post": {"tags": ["Chat"], "summary": "Chat about recording", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["message"], "properties": {"message": {"type": "string"}, "conversation_history": {"type": "array"}}}}}}, "responses": {"200": {"description": "Chat response"}}}+ },+ "/recordings/{id}/events": {+ "get": {"tags": ["Events"], "summary": "Get calendar events", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "List of events"}}}+ },+ "/recordings/{id}/events/ics": {+ "get": {"tags": ["Events"], "summary": "Download events as ICS", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "ICS file", "content": {"text/calendar": {}}}}}+ },+ "/recordings/{id}/audio": {+ "get": {"tags": ["Audio"], "summary": "Download audio", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}, {"name": "download", "in": "query", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Audio file"}}}+ },+ "/recordings/{id}/tags": {+ "post": {"tags": ["Tags"], "summary": "Add tags to recording", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"tag_ids": {"type": "array", "items": {"type": "integer"}}}}}}}, "responses": {"200": {"description": "Tags added"}}}+ },+ "/recordings/{id}/tags/{tag_id}": {+ "delete": {"tags": ["Tags"], "summary": "Remove tag from recording", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}, {"name": "tag_id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Tag removed"}}}+ },+ "/recordings/{id}/speakers": {+ "get": {"tags": ["Speakers"], "summary": "Get speakers in recording", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Speakers with suggestions"}}}+ },+ "/recordings/batch": {+ "patch": {"tags": ["Batch"], "summary": "Batch update recordings", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["recording_ids", "updates"], "properties": {"recording_ids": {"type": "array", "items": {"type": "integer"}}, "updates": {"type": "object"}}}}}}, "responses": {"200": {"description": "Batch results"}}},+ "delete": {"tags": ["Batch"], "summary": "Batch delete recordings", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["recording_ids"], "properties": {"recording_ids": {"type": "array", "items": {"type": "integer"}}}}}}}, "responses": {"200": {"description": "Batch results"}}}+ },+ "/recordings/batch/transcribe": {+ "post": {"tags": ["Batch"], "summary": "Batch queue transcriptions", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["recording_ids"], "properties": {"recording_ids": {"type": "array", "items": {"type": "integer"}}}}}}}, "responses": {"200": {"description": "Batch results"}}}+ },+ "/tags": {+ "get": {"tags": ["Tags"], "summary": "List tags", "responses": {"200": {"description": "List of tags"}}},+ "post": {"tags": ["Tags"], "summary": "Create tag", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}, "color": {"type": "string"}, "custom_prompt": {"type": "string"}, "default_language": {"type": "string"}, "default_min_speakers": {"type": "integer"}, "default_max_speakers": {"type": "integer"}}}}}}, "responses": {"201": {"description": "Tag created"}}}+ },+ "/tags/{id}": {+ "put": {"tags": ["Tags"], "summary": "Update tag", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "color": {"type": "string"}, "custom_prompt": {"type": "string"}}}}}}, "responses": {"200": {"description": "Tag updated"}}},+ "delete": {"tags": ["Tags"], "summary": "Delete tag", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Tag deleted"}}}+ },+ "/speakers": {+ "get": {"tags": ["Speakers"], "summary": "List speakers", "responses": {"200": {"description": "List of speakers"}}},+ "post": {"tags": ["Speakers"], "summary": "Create speaker", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}}}}}}, "responses": {"201": {"description": "Speaker created"}}}+ },+ "/speakers/{id}": {+ "put": {"tags": ["Speakers"], "summary": "Update speaker", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}}}}}}, "responses": {"200": {"description": "Speaker updated"}}},+ "delete": {"tags": ["Speakers"], "summary": "Delete speaker", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Speaker deleted"}}}+ }+ },+ "tags": [+ {"name": "Stats", "description": "System statistics for dashboards"},+ {"name": "Recordings", "description": "Recording CRUD operations"},+ {"name": "Processing", "description": "Transcription and summarization"},+ {"name": "Chat", "description": "Chat with recordings"},+ {"name": "Events", "description": "Calendar events"},+ {"name": "Audio", "description": "Audio file operations"},+ {"name": "Tags", "description": "Tag management"},+ {"name": "Speakers", "description": "Speaker management"},+ {"name": "Batch", "description": "Batch operations"}+ ]+}+++@api_v1_bp.route('/openapi.json', methods=['GET'])+def get_openapi_spec():+ """Return OpenAPI specification."""+ return jsonify(OPENAPI_SPEC)+++@api_v1_bp.route('/docs', methods=['GET'])+def get_docs():+ """Serve Swagger UI documentation."""+ from flask import Response+ html = '''<!DOCTYPE html>+<html>+<head>+ <title>Speakr API v1 Documentation</title>+ <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />+</head>+<body>+ <div id="swagger-ui"></div>+ <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>+ <script>+ SwaggerUIBundle({+ url: "/api/v1/openapi.json",+ dom_id: '#swagger-ui',+ presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],+ layout: "BaseLayout",+ persistAuthorization: true+ });+ </script>+</body>+</html>'''+ return Response(html, mimetype='text/html')++# =============================================================================# Stats Endpoint (Homepage Widget Compatible)# =============================================================================