📄 swagger-to-md

Turn any public Swagger/OpenAPI URL into clean, structured Markdown documentation — right inside Claude Code.

Why · What it generates · Usage · Requirements · How it works · Install

---

🤔 Why

You're integrating with an external API. You open the Swagger UI and start clicking around — it works, but it's slow, hard to share, and disappears the moment you close the tab.

The common workarounds fall short:

• 🖱️ "I'll use Swagger UI" → good for exploring, terrible for offline reference or sharing with the team
• 📋 "I'll copy endpoints into Notion" → manual, error-prone, goes stale the moment the spec changes
• 🤖 "I'll paste the JSON into Claude" → burns context on every single question about the API

swagger-to-md solves this by converting the spec into a Markdown file you own.

One command, one file. Version it in your repo, drop it in your docs, open it in any editor. No browser tab required.

---

📦 What it generates

Running /swagger-to-md https://your-api/swagger.json produces a single .md file with:

Section	What's inside
Header	API title, version, base URL
Authentication	All security schemes with type and flow
Table of Contents	Grouped by tag, linked to each endpoint
Endpoints	One section per route, grouped by tag
Parameters	Full table: name, location, type, required, description
Request Body	JSON example or schema summary
Responses	All status codes with descriptions and example body

---

🚀 Usage

/swagger-to-md [swagger-url] [output-path]

Invocation	Behaviour
/swagger-to-md	Asks for the URL, then asks for the output path
/swagger-to-md https://...	Asks only for the output path
/swagger-to-md https://... ./docs.md	Runs immediately with no prompts

Examples:

# Petstore (classic public example)
/swagger-to-md https://petstore.swagger.io/v2/swagger.json

# OpenAPI 3 YAML spec, custom output path
/swagger-to-md https://api.example.com/openapi.yaml ./docs/api-reference.md

# No arguments — skill will ask for both
/swagger-to-md

---

🔧 Requirements

Dependency	Required for	How to get
curl	Fetching the spec	Pre-installed on most systems
Python 3	Running the parse helper	sudo apt install python3
pyyaml	YAML specs only	pip install pyyaml

JSON specs work with no extra dependencies. YAML specs require PyYAML — the skill will prompt you to install it if it's missing.

---

⚙️ How it works

/swagger-to-md <url> [output-path]
        │
        ▼
   Validate URL (must be http/https)
        │
        ▼
   curl -L <url>  →  /tmp/swagger_spec_raw
        │
        ▼
   scripts/parse.py
     JSON → parsed directly
     YAML → requires pyyaml
        │
        ├── /tmp/swagger_spec.json  (normalised)
        └── stdout: TITLE, VERSION, OAS_VERSION,
                    BASE_URL, ROUTES, METHODS, TAGS
        │
        ▼
   Claude reads the spec and generates Markdown
     • Groups endpoints by tag
     • Tables for parameters
     • JSON examples from spec or schema
     • All status codes documented
        │
        ▼
   Writes to <output-path>  ✅
   Cleans up /tmp files     🗑️

---

📥 Install

Copy this into your Claude Code session:

Install swagger-to-md: https://raw.githubusercontent.com/viniciusNoleto/swagger-to-md/main/SKILL.md

Or manually:

mkdir -p ~/.claude/skills/swagger-to-md/scripts

curl -o ~/.claude/skills/swagger-to-md/SKILL.md \
  https://raw.githubusercontent.com/viniciusNoleto/swagger-to-md/main/SKILL.md

curl -o ~/.claude/skills/swagger-to-md/scripts/parse.py \
  https://raw.githubusercontent.com/viniciusNoleto/swagger-to-md/main/scripts/parse.py

Then in any Claude Code session:

/swagger-to-md https://petstore.swagger.io/v2/swagger.json
# or
/swagger-to-md https://api.example.com/openapi.yaml ./docs/api-reference.md

---

📁 Repository structure

swagger-to-md/
├── SKILL.md          # Skill definition: 9-step workflow for Claude Code
├── scripts/
│   └── parse.py      # Python 3: normalises JSON/YAML spec → JSON + metadata
└── README.md         # This file

---

License

MIT

Star History