Swagger API Code Generator
Generate TypeScript types, interfaces, and API client code directly from Swagger/OpenAPI documentation.
What This Skill Does
This skill enables you to:
Query Swagger/OpenAPI documents to understand available endpointsGenerate TypeScript response types and request interfacesCreate API client implementations based on schema definitionsSearch and filter APIs by tags or keywordsExtract detailed schema information for specific endpointsPrerequisites
The user must have `swagger-mcp-tool` configured in their MCP client settings. For Claude Desktop or Cursor, this means adding an entry like:
```json
{
"mcpServers": {
"swagger-api": {
"command": "npx",
"args": ["-y", "swagger-mcp-tool", "https://example.com/swagger.json"]
}
}
}
```
Instructions
When the user asks you to work with Swagger/OpenAPI documentation or generate API-related code, follow these steps:
Step 1: List Available API Groups
Start by getting an overview of the API structure:
Use the `list_api_groups` tool to see all available tags/groupsPresent the groups to help the user identify relevant endpointsStep 2: Search for Specific APIs
Based on the user's requirements:
Use `search_apis` with the `tag` parameter to filter by groupUse `search_apis` with the `keyword` parameter to search by operation summary or pathCombine both parameters for precise filteringStep 3: Get Detailed Operation Information
For endpoints the user wants to implement:
Use `get_api_detail` with the exact `path` and `method` (e.g., GET, POST, PUT, DELETE)Review the full operation object including parameters, request body, and responsesStep 4: Extract Schema Definitions
When you need type definitions:
Use `get_schema` with the `$ref` value (e.g., "#/components/schemas/Pet") or schema nameGenerate TypeScript interfaces based on the schema propertiesHandle nested schemas by recursively fetching referenced definitionsStep 5: Generate Code
Based on the gathered information:
Create TypeScript type definitions for request/response objectsGenerate API client methods with proper typingInclude error handling and validation where appropriateFollow the user's existing code style and patternsExample Usage
**User request:** "Generate the TypeScript types and API client for the user registration endpoint"
**Your response:**
1. Call `list_api_groups` to understand the structure
2. Call `search_apis` with `keyword: "registration"` or appropriate tag
3. Call `get_api_detail` for the registration endpoint (e.g., path: "/users/register", method: "POST")
4. Call `get_schema` for each referenced schema in the request/response
5. Generate complete TypeScript code with interfaces and API client method
Important Notes
Always start by exploring the API structure before generating codeVerify endpoint paths and methods are exactly as specified in the Swagger docWhen fetching schemas, use the exact `$ref` string from the operation detailGenerate code that matches the user's project conventions (naming, structure, etc.)If multiple Swagger servers are configured, clarify which one the user wants to work withHandle optional vs. required fields correctly based on the schemaInclude JSDoc comments with descriptions from the Swagger documentationConstraints
This skill requires the swagger-mcp-tool MCP server to be properly configuredYou can only work with Swagger/OpenAPI documents that have been loaded into the MCP serverSchema references must exist in the document (you cannot generate arbitrary types)Generated code should be TypeScript (primary use case), but adapt to other languages if the user requests