# Generate API Documentation

Regenerate the Slate API documentation from OpenAPI specs.

## Usage

Run this command when you need to preview documentation changes locally or after modifying OpenAPI specs.

## Steps

1. **Ensure services are running locally**
   ```bash
   ./scripts/dev.sh
   ```

2. **Generate markdown from OpenAPI specs**
   ```bash
   chmod +x docs/scripts/generate-docs.sh
   ./docs/scripts/generate-docs.sh http://localhost
   ```

3. **Build Slate documentation locally** (optional)
   ```bash
   cd docs
   bundle install
   bundle exec middleman serve
   ```
   Then open http://localhost:4567 to preview.

## What This Does

1. Discovers all services with OpenAPI specs
2. Fetches `/openapi.json` from each running service
3. Converts specs to Slate markdown using Widdershins
4. Updates `docs/source/includes/` with service documentation

## CI Pipeline

In production, this process runs automatically:
- CI fetches OpenAPI specs from built service binaries
- Widdershins converts to Slate markdown
- Middleman builds static HTML
- Static files deployed to `docs.{domain}`

## Troubleshooting

- **"Connection refused"**: Ensure services are running on expected ports
- **"No OpenAPI spec found"**: Check that services expose `/openapi.json`
- **"widdershins not found"**: Run `npm install -g widdershins`
- **"bundle not found"**: Install Ruby and run `gem install bundler`