DocPsycho

A GitHub Action that keeps your Spring Boot API documentation in sync with your code automatically.

When a pull request touches a controller or DTO, DocPsycho diffs the affected endpoints, asks Claude to write a precise in-place patch for each doc section, and opens a documentation PR before your code PR lands.

---

How it works

PR touches src/main/java/**
        ↓
  git diff  →  list of changed files
        ↓
  SpecExtractor  →  live OpenAPI spec  (starts the app, fetches /v3/api-docs)
        ↓
  ChangeDetector  →  stale manifest entries  +  undocumented endpoints
        ↓
  PatchGenerator  →  Claude reads controller + DTOs + existing doc section → patch
        ↓
  PrPublisher  →  applies patches to Markdown, commits, opens PR

Each patch targets exactly the heading that documents the changed endpoint — nothing else in the file is touched.

---

Prerequisites

In your Spring Boot project:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

In your GitHub repository:

• ANTHROPIC_API_KEY added as a repository secret (get one at console.anthropic.com)
• gh CLI — pre-installed on ubuntu-latest

---

Quick start

1. Initialize the manifest

Run once from your project root (Java 21 required):

java -jar docsync-cli-exec.jar init --project-dir .

This starts your app, introspects its endpoints, and writes docsync-manifest.json. Commit the file.

2. Map endpoints to documentation

Edit docsync-manifest.json to fill in docSection for each endpoint you want DocPsycho to manage. The format is path/to/file.md#heading-anchor.

{
  "entries": [
    {
      "openapiPath": "POST /api/users",
      "docSection": "docs/api/users.md#create-user",
      "sourceSymbols": [ ... ],
      "contentHash": "..."
    }
  ]
}

Endpoints without a docSection are left alone by the patch generator and instead listed as "undocumented" in every DocPsycho PR — a running checklist.

3. Add the workflow

# .github/workflows/sync-docs.yml
name: Sync API Docs

on:
  pull_request:
    paths:
      - 'src/main/java/**'

permissions:
  contents: write       # push the docs branch
  pull-requests: write  # open the PR

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # full history is required for git diff

      - uses: Rishi6229/docsync@v0.1
        id: docsync
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Show docs PR
        if: steps.docsync.outputs.pr-url != ''
        run: echo "Docs PR → ${{ steps.docsync.outputs.pr-url }}"

---

Inputs

Input	Required	Default	Description
anthropic-api-key	✅	—	Anthropic API key for patch generation
github-token	✅	—	GitHub token for opening PRs — GITHUB_TOKEN is sufficient
project-dir		.	Path to the Spring Boot project, relative to the repo root
base-ref		PR base SHA	Git ref to compare against (defaults to the PR's base commit)
base-branch		main	Target branch for the documentation PR
java-version		21	Java version used to build DocPsycho (must be ≥ 21)

Outputs

Output	Description
pr-url	URL of the documentation PR opened by DocPsycho (empty string if nothing was synced)

---

CLI reference

docsync init

docsync init [--project-dir <dir>] [--commit <sha>]

Starts the target app, fetches its OpenAPI spec, and writes docsync-manifest.json. Run once to set up; re-run after adding endpoints that weren't in the original spec.

docsync sync

docsync sync [--project-dir <dir>] [--base-ref <ref>] [--base-branch <branch>]
             [--repo <owner/repo>] [--dry-run]

The main pipeline — called automatically by the GitHub Action. --dry-run shows what would be patched without calling the API or creating a PR. Requires ANTHROPIC_API_KEY.

---

Building from source

Requires Java 21 and Maven 3.9+.

mvn test      # unit tests only (fast)
mvn verify    # unit + integration tests (starts the fixtures app — takes ~30 s)
mvn package   # build the fat JAR → docsync-cli/target/docsync-cli-*-exec.jar

---

License

MIT — see LICENSE.