# 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