# API Doc

> API Doc is an Agent Skill for documents published in the meshery/meshery repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Document REST API endpoints and GraphQL operations in the Meshery server.

- Skill name: `api-doc`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/meshery/meshery/blob/HEAD/.agents/skills/api-doc/SKILL.md
- Repository: meshery/meshery (11,362 GitHub stars when collected)

## SKILL.md

# Skill: api-doc

Document REST API endpoints and GraphQL operations in the Meshery server.

## Usage

Invoke this skill with a target handler file or directory:
- `/api-doc server/handlers/design_handler.go`
- `/api-doc server/handlers/` (document all handlers)

## Instructions

1. **Read the target handler file(s)** to identify all HTTP endpoint functions.
2. **Read the router configuration** in `server/router/` to find URL paths and HTTP methods mapped to each handler.
3. **Read the request/response model types** in `server/models/` referenced by the handlers.
4. **Generate documentation** in the format below.

### Output Format

For each endpoint, document:

````markdown
### `METHOD /api/path`

**Description**: Brief description of what the endpoint does.

**Authentication**: Required / Not required

**Parameters**:

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| id | path | string | yes | Resource identifier |
| page | query | int | no | Page number (default: 1) |

**Request Body** (if applicable):

```json
{
  "field": "type — description"
}
```

**Response** `200 OK`:

```json
{
  "field": "type — description"
}
```

**Error Responses**:

| Status | Description |
|--------|-------------|
| 400 | Invalid request body |
| 401 | Authentication required |
| 404 | Resource not found |
````

### Guidelines

- Derive descriptions from handler logic and comments — do not invent behavior
- Include all query parameters, path parameters, and headers the handler reads
- Document the actual JSON structure by reading the Go struct tags (`json:"field_name"`)
- Note any middleware applied (auth, rate limiting) visible in the router setup
- For GraphQL, document queries and mutations with their input/output types
- Group endpoints by resource type (designs, patterns, filters, connections, etc.)

---

Source: https://www.openparable.com/skill/documents/api-doc (OpenParable). Cite the canonical URL above.