51 lines
1.4 KiB
Markdown
51 lines
1.4 KiB
Markdown
# 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`
|