stx generate

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

Usage

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:

stx generate --input openapi.json

Supports local files or URLs:

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

Source Code Annotations

Generate docs from @stx annotations in your code:

stx generate --input src/

Scans for annotated functions and generates API documentation.

Examples

From Local OpenAPI File

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

From Remote Spec

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

Watch Mode

Re-generate when the spec changes:

stx generate --input openapi.json --watch

Multiple Specs (Microservices)

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

---
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:

/**
 * @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

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

GraphQL Support

Generate docs from a GraphQL schema:

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:

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

Generates pages for:

• Services and methods
• Message types
• Enums