stardust openapi

Generate Stardust documentation from OpenAPI (Swagger) specifications.

Usage

stardust openapi <spec> [options]

Where <spec> is a path to a local file or a URL to an OpenAPI specification.

Examples

From Local File

stardust openapi ./api/openapi.yaml -o docs/api

From URL

stardust openapi https://api.example.com/openapi.json -o docs/api

With Options

stardust openapi openapi.yaml \
  --output docs/api \
  --group-by tag \
  --include-schemas

Options

Supported Specifications

Both YAML and JSON files are supported.

Output Organization

Group by Path (default)

stardust openapi openapi.yaml --group-by path

docs/api/
├── index.md
├── users/
│   ├── list.md       # GET /users
│   ├── create.md     # POST /users
│   └── get.md        # GET /users/{id}
└── orders/
    ├── list.md       # GET /orders
    └── create.md     # POST /orders

Group by Tag

stardust openapi openapi.yaml --group-by tag

Organizes by the tags defined in your OpenAPI spec:

docs/api/
├── index.md
├── user-management/  # "User Management" tag
│   ├── list-users.md
│   └── create-user.md
└── orders/           # "Orders" tag
    └── create-order.md

Group by Method

stardust openapi openapi.yaml --group-by method

docs/api/
├── index.md
├── get/
│   ├── users.md
│   └── orders.md
├── post/
│   ├── users.md
│   └── orders.md
└── delete/
    └── users.md

Generated Content

Each endpoint page includes:

• HTTP method and path
• Description from spec
• Parameters (path, query, header, body)
• Request body schema
• Response schemas
• Authentication requirements
• Example requests/responses (if in spec)

Example Generated Page

---
title: Get User
description: Retrieve a user by ID
---

# Get User

<Api method="GET" path="/users/{id}" auth="Bearer Token">
  Retrieve a user by their unique identifier.

  <ParamField name="id" type="string" paramType="path" required>
    The user's unique identifier.
  </ParamField>

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

Including Schemas

Generate pages for reusable schemas:

stardust openapi openapi.yaml --include-schemas

Creates additional pages in docs/api/schemas/:

docs/api/
├── index.md
├── users/
│   └── ...
└── schemas/
    ├── User.md
    ├── Order.md
    └── Error.md

Preserving Custom Content

Use --no-overwrite to keep manual edits:

stardust openapi openapi.yaml --no-overwrite

This skips files that already exist, letting you:

• Add custom examples
• Include additional notes
• Modify descriptions

Workflow

stardust openapi openapi.yaml -o docs/api

sidebar:
  - group: API Reference
    autogenerate:
      dir: api

stardust openapi openapi.yaml -o docs/api --no-overwrite

Troubleshooting

Invalid Specification

If you get parsing errors:

• Validate your spec at editor.swagger.io
• Check for syntax errors in YAML/JSON
• Ensure required fields are present

Missing Endpoints

If endpoints are missing:

• Check if they have the deprecated: true flag
• Verify paths are properly defined
• Look for specification validation warnings

URL Access Issues

If fetching from URL fails:

• Check the URL is accessible
• Verify no authentication is required
• Try downloading the file locally first