get-api-spec
Convert Swagger API specifications to minified markdown or JSON format for documentation purposes.
Instructions
Get and convert Swagger specification for an API group to a minified markdown format
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| apigroup_id | Yes | ID of the API group to get specification for | |
| format | No | Output format: 'markdown' for concise documentation or 'json' for full specification | markdown |
Implementation Reference
- src/index.ts:572-637 (handler)Main execution logic for the get-api-spec tool: fetches API group, retrieves Swagger spec via link, processes to markdown or JSON.
async ({ apigroup_id, format }) => { console.error(`[Tool] Executing get-api-spec for API group ID: ${apigroup_id} with format: ${format}`); try { // Step 1: Get the API group details to find the Swagger spec link const apiGroup = await makeXanoRequest<XanoApiGroup>(`/workspace/${XANO_WORKSPACE}/apigroup/${apigroup_id}`); if (!apiGroup.swagger || !apiGroup.documentation || !apiGroup.documentation.link) { return { content: [ { type: "text", text: `API group (ID: ${apigroup_id}) does not have Swagger documentation available.` } ], isError: true }; } console.error(`[Tool] Found Swagger spec link: ${apiGroup.documentation.link}`); // Step 2: Fetch the Swagger JSON specification const swaggerResponse = await fetch(apiGroup.documentation.link); if (!swaggerResponse.ok) { throw new Error(`Failed to fetch Swagger spec: ${swaggerResponse.statusText}`); } const swaggerSpec = await swaggerResponse.json(); console.error(`[Tool] Successfully retrieved Swagger specification`); // Step 3: Process the spec based on format if (format === "json") { // Return the full JSON specification return { content: [ { type: "text", text: `# ${apiGroup.name} API Specification (Full JSON)\n\n\`\`\`json\n${JSON.stringify(swaggerSpec, null, 2)}\n\`\`\`` } ] }; } else { // Process the Swagger spec into a minified markdown format const markdown = processSwaggerToMarkdown(swaggerSpec, apiGroup.name); return { content: [ { type: "text", text: markdown } ] }; } } catch (error) { console.error(`[Error] Failed to get API spec: ${error instanceof Error ? error.message : String(error)}`); return { content: [ { type: "text", text: `Error getting API specification: ${error instanceof Error ? error.message : String(error)}` } ], isError: true }; } } - src/index.ts:568-571 (schema)Zod input schema defining parameters: apigroup_id (string) and format (markdown/json, default markdown).
{ apigroup_id: z.string().describe("ID of the API group to get specification for"), format: z.enum(["markdown", "json"]).default("markdown").describe("Output format: 'markdown' for concise documentation or 'json' for full specification") }, - src/index.ts:565-638 (registration)MCP server.tool registration for the get-api-spec tool, including name, description, input schema, and handler function.
server.tool( "get-api-spec", "Get and convert Swagger specification for an API group to a minified markdown format", { apigroup_id: z.string().describe("ID of the API group to get specification for"), format: z.enum(["markdown", "json"]).default("markdown").describe("Output format: 'markdown' for concise documentation or 'json' for full specification") }, async ({ apigroup_id, format }) => { console.error(`[Tool] Executing get-api-spec for API group ID: ${apigroup_id} with format: ${format}`); try { // Step 1: Get the API group details to find the Swagger spec link const apiGroup = await makeXanoRequest<XanoApiGroup>(`/workspace/${XANO_WORKSPACE}/apigroup/${apigroup_id}`); if (!apiGroup.swagger || !apiGroup.documentation || !apiGroup.documentation.link) { return { content: [ { type: "text", text: `API group (ID: ${apigroup_id}) does not have Swagger documentation available.` } ], isError: true }; } console.error(`[Tool] Found Swagger spec link: ${apiGroup.documentation.link}`); // Step 2: Fetch the Swagger JSON specification const swaggerResponse = await fetch(apiGroup.documentation.link); if (!swaggerResponse.ok) { throw new Error(`Failed to fetch Swagger spec: ${swaggerResponse.statusText}`); } const swaggerSpec = await swaggerResponse.json(); console.error(`[Tool] Successfully retrieved Swagger specification`); // Step 3: Process the spec based on format if (format === "json") { // Return the full JSON specification return { content: [ { type: "text", text: `# ${apiGroup.name} API Specification (Full JSON)\n\n\`\`\`json\n${JSON.stringify(swaggerSpec, null, 2)}\n\`\`\`` } ] }; } else { // Process the Swagger spec into a minified markdown format const markdown = processSwaggerToMarkdown(swaggerSpec, apiGroup.name); return { content: [ { type: "text", text: markdown } ] }; } } catch (error) { console.error(`[Error] Failed to get API spec: ${error instanceof Error ? error.message : String(error)}`); return { content: [ { type: "text", text: `Error getting API specification: ${error instanceof Error ? error.message : String(error)}` } ], isError: true }; } } ); - src/index.ts:640-715 (helper)Supporting function that converts raw Swagger/OpenAPI JSON specification into a concise, minified markdown documentation format for the tool's markdown output.
// Helper function to process Swagger spec into concise markdown function processSwaggerToMarkdown(swaggerSpec: any, apiGroupName: string): string { try { console.error(`[Process] Converting Swagger spec to markdown for: ${apiGroupName}`); // Extract basic API information const info = swaggerSpec.info || {}; const server = swaggerSpec.servers?.[0]?.url || 'https://'; const baseUrl = server; // Build the markdown content let markdown = `# ${apiGroupName} API\n\n`; markdown += `## API Info\n`; markdown += `- Title: ${info.title || apiGroupName}\n`; markdown += `- Version: ${info.version || 'N/A'}\n`; markdown += `- Base URL: ${baseUrl}\n\n`; // Common responses markdown += `## Responses\n`; markdown += `| Code | Description |\n`; markdown += `|------|-------------|\n`; markdown += `| 200 | Success! |\n`; markdown += `| 400 | Input Error |\n`; markdown += `| 401 | Unauthorized|\n`; markdown += `| 403 | Access Denied|\n`; markdown += `| 404 | Not Found |\n`; markdown += `| 429 | Rate Limited|\n`; markdown += `| 500 | Server Error|\n\n`; // Process endpoints markdown += `## Endpoints\n\n`; const paths = swaggerSpec.paths || {}; const pathKeys = Object.keys(paths).sort(); for (const path of pathKeys) { const pathInfo = paths[path]; const methods = Object.keys(pathInfo).filter(m => ['get', 'post', 'put', 'delete', 'patch'].includes(m.toLowerCase())); for (const method of methods) { const operation = pathInfo[method]; markdown += `### ${method.toUpperCase()} ${path}\n`; markdown += `${operation.summary || 'No summary'}\n`; // Parameters const parameters = operation.parameters || []; if (parameters.length > 0) { markdown += `| Param | In | Req | Type |\n`; markdown += `|-------|----|-----|------|\n`; for (const param of parameters) { markdown += `| ${param.name} | ${param.in} | ${param.required ? 'Y' : 'N'} | ${param.schema?.type || 'unknown'} |\n`; } } markdown += '\n'; } } // Authentication const securitySchemes = swaggerSpec.components?.securitySchemes || {}; if (Object.keys(securitySchemes).length > 0) { markdown += `## Auth\n`; for (const name in securitySchemes) { const scheme = securitySchemes[name]; markdown += `- ${name}: ${scheme.type}`; if (scheme.scheme) markdown += ` (${scheme.scheme})`; markdown += '\n'; } } console.error(`[Process] Successfully converted Swagger spec to markdown`); return markdown; } catch (error) { console.error(`[Error] Error processing Swagger to Markdown: ${error instanceof Error ? error.message : String(error)}`); return `# Error\n\n${error instanceof Error ? error.message : String(error)}`; } }