Prompt
I'm building docs from OpenAPI and want to keep everything in Git
Latest observation
Oct 16, 2026
OpenAI APIWeb search: off
A good pattern is:
-
Keep the OpenAPI spec in Git
- Store
openapi.yamloropenapi.jsonin the repo. - Treat it as the source of truth.
- Store
-
Generate docs from the spec in CI
- Use a docs generator like:
- Redoc / Redocly
- Swagger UI
- Docusaurus + OpenAPI plugins
- ReDocly CLI
- Run generation in GitHub Actions / GitLab CI / etc.
- Use a docs generator like:
-
Commit the generated docs only if you really need them in the repo
- If you want versioned static docs, you can commit the output to a
docs/orsite/folder. - Otherwise, publish the generated site as an artifact or deploy it to GitHub Pages, S3, Netlify, etc.
- If you want versioned static docs, you can commit the output to a
-
Automate the sync
- On every PR:
- validate the OpenAPI file
- generate docs
- fail if the generated output is stale
- On merge to main:
- regenerate and publish/commit
- On every PR:
-
Avoid manual editing of generated files
- Keep human-authored content separate from generated content.
- Example:
api/openapi.yaml— sourcedocs/— generated outputdocs/guide/— hand-written docs
A practical repo layout:
repo/
api/
openapi.yaml
docs/
guide/
api/ # generated
package.json
.github/workflows/docs.yml
If you want, I can give you:
- a GitHub Actions workflow
- a Redocly or Swagger UI setup
- or a recommended repo structure for docs + OpenAPI in Git.