---
title: stx generate
description: Generate API documentation from OpenAPI specs or source code annotations.
icon: sparkles
---

# stx generate

Generate API reference documentation from OpenAPI specifications or source code with `@stx` annotations.

## Usage

```bash
stx generate [source] [options]
```

## Options

| Flag | Alias | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--input` | `-i` | string | `openapi.json` | Input file path or URL |
| `--output` | `-o` | string | `docs/api-reference` | Output directory |
| `--format` | `-f` | string | `mdx` | Output format: `mdx`, `json` |
| `--overwrite` | | boolean | `false` | Overwrite existing files |
| `--watch` | `-w` | boolean | `false` | Watch for changes |

## Sources

### OpenAPI Specification

Generate docs from an OpenAPI 3.x spec:

```bash
stx generate --input openapi.json
```

Supports local files or URLs:

```bash
stx generate --input https://api.example.com/openapi.json
```

### Source Code Annotations

Generate docs from `@stx` annotations in your code:

```bash
stx generate --input src/
```

Scans for annotated functions and generates API documentation.

## Examples

### From Local OpenAPI File

```bash
stx generate --input ./api/openapi.yaml --output docs/api-reference
```

### From Remote Spec

```bash
stx generate --input https://petstore.swagger.io/v2/swagger.json
```

### Watch Mode

Re-generate when the spec changes:

```bash
stx generate --input openapi.json --watch
```

### Multiple Specs (Microservices)

```bash
stx generate --input services/users/openapi.json --output docs/api/users
stx generate --input services/orders/openapi.json --output docs/api/orders
```

## Generated Output

### File Structure

```
docs/api-reference/
├── overview.mdx
├── authentication.mdx
├── users/
│   ├── create-user.mdx
│   ├── get-user.mdx
│   ├── update-user.mdx
│   └── delete-user.mdx
└── orders/
    ├── create-order.mdx
    └── list-orders.mdx
```

### Generated Page Example

```mdx
---
title: Create User
protocol: rest
method: POST
endpoint: /v1/users
description: Create a new user account
---

# Create User

Create a new user account with the provided details.

<Endpoint method="POST" path="/v1/users" />

## Request Body

<ParamField name="email" type="string" required>
  User's email address. Must be unique.
</ParamField>

<ParamField name="name" type="string" required>
  User's display name.
</ParamField>

<ParamField name="role" type="string" default="member">
  User role. One of: `admin`, `editor`, `member`.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique user identifier.
</ResponseField>

<ResponseField name="email" type="string">
  User's email address.
</ResponseField>

## Code Examples

<CodeGroup>
\`\`\`bash title="cURL"
curl -X POST https://api.example.com/v1/users \\
  -H "Authorization: Bearer $API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"email": "alice@example.com", "name": "Alice"}'
\`\`\`

\`\`\`typescript title="TypeScript"
const user = await client.users.create({
  email: "alice@example.com",
  name: "Alice"
})
\`\`\`
</CodeGroup>
```

## Source Code Annotations

### @stx Annotation Syntax

Add `@stx` directives in your doc comments:

```typescript
/**
 * @stx group "Users"
 * @stx title "Create User"
 * @stx description "Create a new user account"
 */
export async function createUser(data: CreateUserInput): Promise<User> {
  // ...
}
```

### Supported Languages

| Language | Comment Style | Example |
|----------|--------------|---------|
| TypeScript/JavaScript | `/** ... */` | `@stx title "..."` |
| Python | `"""..."""` | `@stx title "..."` |
| Go | `// ...` | `// @stx title "..."` |
| Rust | `/// ...` | `/// @stx title "..."` |
| Java/Kotlin | `/** ... */` | `@stx title "..."` |

### Available Directives

| Directive | Description |
|-----------|-------------|
| `@stx group "Name"` | Group/section name |
| `@stx title "Name"` | Page title |
| `@stx description "..."` | Short description |
| `@stx param name {type} desc` | Parameter documentation |
| `@stx returns {type} desc` | Return value documentation |
| `@stx example` | Code example (until next directive) |
| `@stx internal` | Exclude from public docs |

<Note>
When `@stx` annotations are present, they take precedence over conventional doc comments (JSDoc, docstrings, etc.).
</Note>

## GraphQL Support

Generate docs from a GraphQL schema:

```bash
stx generate --input schema.graphql --output docs/graphql
```

Generates pages for:
- Types and interfaces
- Queries and mutations
- Subscriptions
- Enums and scalars

## gRPC/Protobuf Support

Generate docs from `.proto` files:

```bash
stx generate --input proto/ --output docs/grpc
```

Generates pages for:
- Services and methods
- Message types
- Enums