From 14ce2a85866070db37bd471adb2da98c8a2ec9e8 Mon Sep 17 00:00:00 2001 From: Jarian Cottingham Date: Tue, 3 Feb 2026 21:57:25 +0000 Subject: [PATCH] Add OpenAPI specification file for full MCP and API compliance --- openapi.json | 324 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 324 insertions(+) create mode 100644 openapi.json diff --git a/openapi.json b/openapi.json new file mode 100644 index 0000000..7c6318f --- /dev/null +++ b/openapi.json @@ -0,0 +1,324 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "YouTube CLI API", + "version": "1.0.0", + "description": "REST API for YouTube CLI application with MCP compliance", + "contact": { + "name": "YouTube CLI Team" + } + }, + "servers": [ + { + "url": "http://localhost:4096", + "description": "Local development server" + } + ], + "paths": { + "/search": { + "get": { + "summary": "Search YouTube videos", + "description": "Search YouTube videos based on a query string", + "operationId": "searchVideos", + "parameters": [ + { + "name": "q", + "in": "query", + "description": "Search query string", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "Page number for results", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + } + ], + "responses": { + "200": { + "description": "Successful search response", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "query": { + "type": "string" + }, + "page": { + "type": "integer" + }, + "videos": { + "type": "array", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "author": { + "type": "string" + }, + "length": { + "type": "string" + }, + "url": { + "type": "string" + }, + "is_short": { + "type": "boolean" + }, + "is_playlist": { + "type": "boolean" + }, + "id": { + "type": "string" + }, + "thumbnail": { + "type": "string" + }, + "view_count": { + "type": "integer" + } + } + } + }, + "total": { + "type": "integer" + } + } + } + } + } + }, + "400": { + "description": "Bad request - missing query parameter" + }, + "500": { + "description": "Internal server error" + } + } + } + }, + "/download": { + "post": { + "summary": "Download a video", + "description": "Initiate download of a video by URL", + "operationId": "downloadVideo", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "YouTube video URL" + } + }, + "required": ["url"] + } + } + } + }, + "responses": { + "200": { + "description": "Download started successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "url": { + "type": "string" + }, + "message": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "Bad request - missing URL" + }, + "500": { + "description": "Internal server error" + } + } + } + }, + "/health": { + "get": { + "summary": "Health check", + "description": "Check if the service is healthy and running", + "operationId": "healthCheck", + "responses": { + "200": { + "description": "Service is healthy", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "service": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "/version": { + "get": { + "summary": "Get API version", + "description": "Get the current version of the API", + "operationId": "getVersion", + "responses": { + "200": { + "description": "API version information", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "version": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "/capabilities": { + "get": { + "summary": "MCP Capabilities", + "description": "Get MCP capabilities information for this service", + "operationId": "getCapabilities", + "responses": { + "200": { + "description": "MCP capabilities information", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "description": { + "type": "string" + }, + "endpoints": { + "type": "array", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string" + }, + "method": { + "type": "string" + }, + "description": { + "type": "string" + } + } + } + }, + "features": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "Video": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "author": { + "type": "string" + }, + "length": { + "type": "string" + }, + "url": { + "type": "string" + }, + "is_short": { + "type": "boolean" + }, + "is_playlist": { + "type": "boolean" + }, + "id": { + "type": "string" + }, + "thumbnail": { + "type": "string" + }, + "view_count": { + "type": "integer" + } + } + }, + "SearchResult": { + "type": "object", + "properties": { + "query": { + "type": "string" + }, + "page": { + "type": "integer" + }, + "videos": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Video" + } + }, + "total": { + "type": "integer" + } + } + } + } + } +} \ No newline at end of file