writing-openapi-specs

Files (9)

• SKILL.md
• components.md · reference/
• examples.md · reference/
• operations.md · reference/
• parameters.md · reference/
• request-bodies.md · reference/
• responses.md · reference/
• schemas.md · reference/
• security.md · reference/

SKILL.md (first lines)

# Writing OpenAPI Specs

Reference for OpenAPI best practices and conventions. This skill provides guidance on taste, conventions, and grey areas not covered by the OpenAPI specification itself.

## When to Use This Skill

- Writing a new OpenAPI specification
- Improving operation naming and organization
- Expressing complex data types (enums, polymorphism, nullable)
- Handling file uploads, streaming, or server-sent events
- Making specs more code-gen friendly
- Understanding reusability patterns (components vs inline)

## Core Principles

### Naming Conventions

**Operation IDs**: Use lowercase with underscores, following `resource_action` pattern:

```yaml
# Good
operationId: users_list
operationId: users_get
operationId: users_create

# Avoid
operationId: GetApiV1Users    # Auto-generated, not semantic
```

**Component Names**: Use PascalCase for schemas, parameters, and other reusable components:

```yaml
components:
  schemas:
    UserProfile:      # PascalCase
    OrderHistory:     # PascalCase
  parameters:
    PageLimit:        # PascalCase
```

**Tags**: Use lowercase with hyphens for machine-friendly tags:

```yaml
tags:
  - name: user-management
    description: Operations for managing users
  - name: order-processing
    description: Operations for processing orders
```

For more details, see [reference/operations.md](reference/operations.md) and [reference/components.md](reference/components.md).

### Documentation Standards

**Use CommonMark**: All `description` fields support CommonMark syntax for rich formatting:

```yaml
description: |
  Retrieves a user by ID.

  ## Authorization
  Requires `users:read` scope.

  ## Rate Limits
  - 100 requests per minute per API key
  - 1000 requests per hour per IP
```

**Be Specific**: Provide actionable information, not generic descriptions:

```yaml
# Good
description: Returns a paginated list of active users, ordered by creation date (newest first)

# Avoid
description: Gets users
```

**Use `examples` over `example`**: The plural `examples` field provides better SDK generation:

```yaml
# Good
examples:
  basic_user:
    value:
      id: 123
      name: "John Doe"
  admin_user:
    value:
      id: 456
      name: "Jane Admin"
      role: admin

# Avoid single example
example:
  id: 123
  name: "John Doe"
```

For more details, see [reference/examples.md](reference/examples.md).

### Reusability

**Create components for**:
- Schemas used in multiple operations
- Common parameters (pagination, filtering)
- Common responses (errors, success patterns)
- Security schemes

**Keep inline for**:
- Operation-specific request bodies
- Unique response shapes
- One-off parameters

```yaml
# Reusable schema
components:
  schemas:
    User:

From speakeasy-api/sdk-generation-skills, Apache-2.0.

More from speakeasy-api/sdk-generation-skills