openapi-parser

# OpenAPI Parser

Parse OpenAPI specifications and extract structured endpoint information for code generation.

---

## EXECUTION INSTRUCTIONS

When this skill is invoked, Claude MUST perform these steps in order:

### Step 1: Load Specification

**Determine source type:**
- If source starts with `http://` or `https://` → Remote URL
- Otherwise → Local file

**For Remote URL:**
1. Use `WebFetch` tool to fetch the content
2. Extract JSON from response
3. If 404 → Error: `❌ Spec not found at URL`
4. If other error → Error: `❌ Failed to fetch: <error>`

**For Local File:**
1. Use `Read` tool to read the file
2. If `.yaml` or `.yml` extension → Parse as YAML
3. If `.json` extension or no extension → Parse as JSON
4. If file not found → Error: `❌ File not found: <path>`
5. If parse error → Error: `❌ Invalid format: <error>`

### Step 2: Validate Specification

Check for valid OpenAPI/Swagger structure:

1. **Version Check:**
   - If has `openapi` field (e.g., "3.0.0", "3.1.0") → OpenAPI 3.x
   - If has `swagger` field (e.g., "2.0") → Swagger 2.0
   - If neither → Error: `❌ Not a valid OpenAPI/Swagger spec`

2. **Required Fields:**
   - Must have `info` object with `title` and `version`
   - Must have `paths` object
   - If missing → Error: `❌ Missing required field: <field>`

3. **Report:**
   ```
   📄 OpenAPI: <title> v<version>
      Spec version: <openapi/swagger version>
      Endpoints: <count>
   ```

### Step 3: Convert Swagger 2.0 (if needed)

If Swagger 2.0, convert to OpenAPI 3.0 format internally:

| Swagger 2.0 | OpenAPI 3.0 |
|-------------|-------------|
| `definitions` | `components.schemas` |
| `parameters` (body) | `requestBody` |
| `produces`/`consumes` | `content` with media types |
| `securityDefinitions` | `components.securitySchemes` |

### Step 4: Extract Metadata

Extract and store:
```json
{
  "title": "<info.title>",
  "version": "<info.version>",
  "description": "<info.description or null>",
  "servers": ["<server urls>"],
  "specVersion": "