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:

{
  "title": "<info.title>",
  "version": "<info.version>",
  "description": "<info.description or null>",
  "servers": ["<server urls>"],
  "specVersion": "<openapi or swagger version>"
}