Generate developer, user, and changelog MDX from a base..head diff. Optionally open a docs PR and trigger a workflow build.

Docs — Generate from Diff

POST /api/docs/generate

Generate documentation drafts by comparing a base and head ref in your repository. The route is protected and requires a valid session (see validateUserSession()).

Request

{
  "repo": "owner/name",        // required
  "base": "main",              // required (base ref)
  "head": "feature-branch",    // required (head ref)
  "ticketId": "TCK-123",       // optional (for frontmatter)
  "prNumber": 57,               // optional (for titles/links)
  "audience": "both",          // optional: developer | user | both
  "openPr": true,               // optional: open a PR with generated docs
  "labels": ["documentation"], // optional: PR labels
  "triggerWorkflow": true,      // optional: trigger CI workflow after PR
  "workflowIdOrFile": "docs.yml", // optional: GitHub Actions file or ID
  "workflowRef": "docs/1725680000000" // optional: ref to run workflow on (defaults to PR branch)
}

Response

When openPr is false:

{
  "summary": "Updated 5 files...",
  "docs": [
    { "path": "content/docs/developer/2025-09-06-api-and-ui-updates.mdx", "content": "..." },
    { "path": "content/docs/user/2025-09-06-api-and-ui-updates.mdx", "content": "..." },
    { "path": "content/docs/changelog/2025-09-06-api-and-ui-updates.mdx", "content": "..." }
  ]
}

When openPr is true:

{
  "summary": "Updated 5 files...",
  "pr": { "url": "https://github.com/owner/name/pull/58", "number": 58, "branch": "docs/1725680000000" },
  "workflow": { "url": "https://github.com/owner/name/actions/workflows/docs.yml", "id": "owner/name/docs.yml@docs/1725680000000" }
}

Notes

  • Uses GitHub via GithubRepoService internally; other providers can implement RepoService.
  • Writes MDX under content/docs/{developer|user|changelog}/ with frontmatter for OMS compatibility.
  • Safe to run repeatedly; if PR creation is enabled, labels like documentation help reviewers triage.
  • Useful for integrating with the Healing Loop: after PRs merge, this route can be called to keep docs fresh.