API Guidelines CLI

A TypeScript CLI tool that maintains API guidelines as a single source of truth and generates multiple output formats including full documentation, reference guides, and Spectral rulesets.

Problem Statement

Managing API guidelines across multiple formats leads to synchronization issues:

• Full Documentation: Detailed markdown with examples and explanations
• Reference Guide: Quick-reference list of rules by severity
• Spectral Ruleset: Automated validation rules for OpenAPI specs

This tool solves the single source of truth problem by maintaining guidelines in structured YAML files and generating all outputs automatically.

Features

• ✅ Single Source of Truth: Define guidelines once in YAML format
• ✅ Multiple Output Formats: Generate docs, reference guides, and Spectral rulesets
• ✅ Flexible Spectral Rules: Support both inline and external rule definitions
• ✅ Content Separation: Keep detailed explanations in separate markdown files
• ✅ Type-Safe: Full TypeScript implementation with Zod validation
• ✅ Extensible: Easy to add new output formats

Installation

# Install dependencies (use npm or pnpm)
npm install

# Build the project (optional - tsx runs TypeScript directly)
npm run build

Project Structure

api-guidelines/
├── src/
│   ├── guidelines/           # Source of truth - YAML files
│   │   ├── naming.yaml
│   │   └── versioning.yaml
│   ├── content/              # Detailed markdown content
│   │   ├── naming-conventions.md
│   │   └── versioning.md
│   ├── spectral-rules/       # Optional external Spectral rules
│   │   └── versioning.yaml
│   ├── types/                # TypeScript types and schemas
│   ├── generators/           # Output generators
│   ├── utils/                # Loader and validator utilities
│   └── cli.ts                # CLI entry point
├── dist/                     # Generated outputs (gitignored)
└── package.json

Usage

Generate All Outputs

npm run generate

This generates:

• dist/api-guidelines.md - Full documentation with examples
• dist/api-reference.md - Quick reference by severity
• dist/.spectral.yaml - Spectral ruleset

Generate Specific Output

npm run generate:docs       # Full documentation only
npm run generate:reference  # Reference guide only
npm run generate:spectral   # Spectral ruleset only

Validate Guidelines

npm run validate

Validates all guideline YAML files without generating outputs.

List Guidelines

# Human-readable list
npx tsx src/cli.ts list

# JSON output
npx tsx src/cli.ts list --json

Guideline File Format

Guidelines are defined in YAML files in the src/guidelines/ directory.

Basic Structure

guidelines:
  - id: pzu:rest5:2025-general-naming-conventions
    title: Ogólne Zasady Nazewnictwa
    category: naming
    content: ../content/naming-conventions.md
    rules:
      - level: must
        text: Identyfikator MUSI być zapisany małymi literami
      - level: must
        text: Identyfikator MUSI używać konwencji camelCase dla złożonych słów
      - level: should-not
        text: Identyfikator NIE POWINIEN zawierać akronimów biznesowych
    spectral:
      # ... spectral rule definition

Severity Levels

Following RFC 2119:

• must - Required (Spectral: error)
• must-not - Prohibited (Spectral: error)
• should - Recommended (Spectral: warn)
• should-not - Not recommended (Spectral: warn)
• may - Optional (Spectral: info)

Spectral Rules - Inline Definition

Define Spectral rules directly in the guideline file:

spectral:
  description: "Each JSON property identifier SHOULD be written in camelCase"
  message: "Property identifier '{{property}}' SHOULD be in camelCase"
  severity: warn
  given:
    - $.components..properties[*]~
    - $.paths[*][*].responses[*].content[*].schema..properties[*]~
  then:
    function: pattern
    functionOptions:
      match: "^(_link|_?[a-z]+([A-Z][a-z]+)*)$"

Spectral Rules - External Reference

Reference an external Spectral rule file:

spectral:
  external: ../spectral-rules/versioning.yaml#pzu:rest5:2025-api-versioning

The external file should contain standard Spectral rule format:

# src/spectral-rules/versioning.yaml
pzu:rest5:2025-api-versioning:
  description: "API paths MUST include version number"
  message: "API path '{{path}}' MUST include version (e.g., /v1/)"
  severity: error
  given:
    - $.paths[*]~
  then:
    function: pattern
    functionOptions:
      match: "^/v[0-9]+/"

Content Files

Detailed explanations, examples, and rationale are stored in separate markdown files in src/content/. These files are referenced from guideline YAML files.

Example structure:

#### Detailed Explanation

Proper naming conventions ensure consistency...

#### Examples

**Good Examples:**
\`\`\`json
{
  "userId": "12345",
  "firstName": "Jan"
}
\`\`\`

#### Rationale

- Consistency: Uniform naming makes APIs easier to learn
- Developer Experience: camelCase is widely adopted

CLI Commands

Generate

tsx src/cli.ts generate [options]

Options:
  -t, --type <type>     Type: docs, reference, spectral, or all (default: "all")
  -s, --source <dir>    Source directory (default: "src/guidelines")
  -o, --output <dir>    Output directory (default: "dist")

Validate

tsx src/cli.ts validate [options]

Options:
  -s, --source <dir>    Source directory (default: "src/guidelines")

List

tsx src/cli.ts list [options]

Options:
  -s, --source <dir>    Source directory (default: "src/guidelines")
  --json                Output as JSON

Development

Watch Mode

npm run dev

Runs the CLI in watch mode, automatically reloading on file changes.

Adding New Guidelines

1. Create a YAML file in src/guidelines/ (or use existing)
2. Define the guideline with id, title, category, rules
3. Create corresponding content file in src/content/
4. Optionally add Spectral rule (inline or external)
5. Run npm run validate to check for errors
6. Run npm run generate to create outputs

Adding New Output Formats

1. Create a new generator in src/generators/
2. Implement the generation logic
3. Add command option in src/cli.ts
4. Update package.json scripts

Extensibility

The architecture supports future enhancements:

• New output formats: Add generators (HTML, JSON, Docusaurus, etc.)
• API documentation sites: Generate static site configs
• IDE plugins: Export as JSON for tooling integration
• Custom validation: Add business-specific validators
• Interactive docs: Generate searchable web interfaces

TypeScript Types

All types are defined in src/types/guideline.ts with Zod schemas for runtime validation:

• Guideline - Main guideline structure
• GuidelineRule - Individual rule
• SpectralRuleInline - Inline Spectral definition
• SpectralRuleExternal - External Spectral reference
• Severity - RFC 2119 severity levels

License

MIT

Contributing

1. Create guideline files following the schema
2. Validate with pnpm validate
3. Generate outputs with pnpm generate
4. Test the generated files
5. Commit source files only (dist/ is gitignored)