feat: docs

README.md

@@ -0,0 +1,171 @@
+# SpecGraph
+
+A visual OpenAPI specification explorer that combines a YAML editor, interactive endpoint graph visualization, and API testing interface.
+
+![SpecGraph](./assets/specgraph.png)
+
+## Features
+
+### 📝 OpenAPI YAML Editor
+- Syntax-highlighted YAML editor with CodeMirror
+- Paste your OpenAPI specification and automatically parse it
+- Click nodes in the graph to jump to the corresponding endpoint in the YAML
+
+### 📊 Interactive Endpoint Graph
+- Visualizes all API endpoints as a force-directed graph using D3.js
+- Nodes represent URL path segments (e.g., `/api/test/bla` creates nodes: `/` → `api` → `test` → `bla`)
+- Left-to-right layout shows the hierarchy of your API structure
+- Hover over nodes to highlight connected links
+- Click nodes to:
+  - Jump to the endpoint in the YAML editor (when on YAML tab)
+  - Expand the operation form (when on Form tab)
+
+### 🧪 API Testing Interface
+- Form-based interface for testing each endpoint
+- Server selection dropdown populated from OpenAPI `servers` field
+- Custom headers support - add any HTTP headers you need
+- Automatic form generation based on:
+  - Path parameters (`{param}`)
+  - Query parameters
+  - Request body (JSON) for POST/PUT/PATCH requests
+- Collapsible operation cards (collapsed by default)
+- Response display in formatted JSON
+
+### 🔄 Backend Proxy
+- Node.js backend acts as a proxy to call your target servers
+- Handles CORS and cross-origin requests
+- Supports all HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
+
+## Getting Started
+
+### Prerequisites
+- Node.js (v16+ recommended)
+
+### Installation
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Start the server:
+```bash
+npm start
+```
+
+3. Open your browser and navigate to:
+```
+http://localhost:3000
+```
+
+## Usage
+
+1. **Load your OpenAPI spec**: Paste your OpenAPI YAML specification in the left panel
+2. **Render the graph**: Click the "Render" button to parse and visualize
+3. **Explore endpoints**: 
+   - Switch to the "Form" tab to test endpoints
+   - Select a server from the dropdown
+   - Expand operations to see their forms
+   - Add custom headers if needed
+   - Fill in parameters and send requests
+4. **Navigate the graph**: Click nodes to jump to endpoints or expand operations
+
+## Project Structure
+
+```
+specgraph/
+├── server.js          # Express backend with parse and proxy endpoints
+├── public/
+│   ├── index.html     # Main HTML structure
+│   ├── styles.css     # All styling
+│   ├── app.js         # Frontend logic (tabs, forms, YAML editor)
+│   └── graph.js       # D3.js graph rendering and interactions
+└── package.json       # Dependencies and scripts
+```
+
+## API Endpoints
+
+### `POST /api/parse`
+Parses OpenAPI YAML and returns graph structure, operations, and servers.
+
+**Request:**
+```json
+{
+  "yaml": "openapi: 3.0.0\n..."
+}
+```
+
+**Response:**
+```json
+{
+  "graph": {
+    "nodes": [...],
+    "links": [...],
+    "endpoints": [...],
+    "operations": [...]
+  },
+  "info": {
+    "title": "API Title",
+    "version": "1.0.0"
+  },
+  "servers": ["https://api.example.com"]
+}
+```
+
+### `POST /api/proxy`
+Proxies HTTP requests to target servers.
+
+**Request:**
+```json
+{
+  "baseUrl": "https://api.example.com",
+  "method": "GET",
+  "path": "/users/123",
+  "query": {"filter": "active"},
+  "headers": {"Authorization": "Bearer token"},
+  "body": {...}
+}
+```
+
+## Technologies
+
+- **Frontend**: Vanilla JavaScript, D3.js v7, CodeMirror 5
+- **Backend**: Node.js, Express 4
+- **Dependencies**: 
+  - `express` - Web server
+  - `js-yaml` - YAML parsing
+  - `node-fetch` - HTTP proxy requests
+
+## Features in Detail
+
+### Graph Visualization
+- Force-directed layout with left-to-right hierarchy
+- Nodes avoid overlapping with unrelated links
+- Smooth animations and drag-to-reposition
+- Zoom and pan support
+
+### Form Generation
+- Automatically detects path parameters and generates inputs
+- Extracts query parameters from OpenAPI spec
+- Supports JSON request bodies for appropriate methods
+- Collapsible UI keeps the interface clean
+
+### YAML Integration
+- Live syntax highlighting
+- Auto-parse on paste
+- Click-to-navigate from graph to YAML
+- Line selection and scrolling
+
+## Example OpenAPI Spec
+
+The app comes with a sample httpbin.org specification that demonstrates:
+- Multiple HTTP methods (GET, POST, PUT, PATCH, DELETE)
+- Query parameters
+- Request bodies
+- Path parameters
+
+You can replace it with your own OpenAPI specification.
+
+## License
+
+ISC