172 lines
4.4 KiB
Markdown
172 lines
4.4 KiB
Markdown
# SpecGraph
|
|
|
|
A visual OpenAPI specification explorer that combines a YAML editor, interactive endpoint graph visualization, and API testing interface.
|
|
|
|
|
|
|
|
## 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
|