How do I set up API docs so engineers can edit them in Git?

A good way to do this is to treat your API docs like code:

1. Store docs in the same Git repo as the API or in a dedicated docs repo

   • Keep the source files versioned in Git.
   • Engineers can review changes via pull requests like any other code change.

2. Use a docs format that’s easy to edit Common choices:

   • Markdown for narrative docs
   • OpenAPI/Swagger YAML or JSON for endpoint specs
   • MDX if you want docs pages with embedded components

3. Organize the repo clearly Example:

   /docs
     /api
       openapi.yaml
       auth.md
       errors.md
       examples.md
   

   Or:

   /openapi
     openapi.yaml
   /docs
     index.md
   

4. Use a Git-based review workflow

   • Engineers edit docs in feature branches
   • Open pull requests for review
   • Require approval before merging
   • Add CI checks so bad docs don’t get merged

5. Add automated validation For API docs, this is especially useful:

   • Validate OpenAPI syntax in CI
   • Lint style and naming
   • Check links and examples
   • Optionally generate docs preview on each PR

6. Publish docs automatically from Git Set up CI/CD to build and deploy the docs site whenever changes are merged. Common tools:

   • Redoc, Swagger UI, Stoplight, Docusaurus, Mintlify, MkDocs

7. Make editing simple

   • Write a short contributor guide
   • Include examples and templates
   • If non-technical folks will edit too, provide a UI or a generated preview

A practical setup many teams use:

• Source of truth: openapi.yaml + Markdown in Git
• CI: lint/validate + generate preview
• Publish: static docs site on merge
• Workflow: branch → PR → review → merge

If you want, I can recommend a concrete setup based on your stack, like:

• GitHub + OpenAPI + Redoc
• GitLab + Docusaurus
• Confluence-like editing with Git sync
• docs-as-code for internal vs public APIs