Implementing a Multi-Agent Workflow for Automated API Documentation using LangGraph

Stop manually updating Swagger docs every time a PR hits production; it's a waste of developer brainpower. I've spent the last few sprints building an automated pipeline using LangGraph to handle API documentation, and the "multi-agent" approach is the only way to get output that isn't hallucinated garbage.

The core problem with a single LLM prompt for docs is that it tries to be the coder and the technical writer simultaneously. It misses edge cases or makes up parameters. My current workflow splits this into three distinct nodes: the Code Analyst, the Doc Writer, and the Validator.

The Analyst node takes the raw FastAPI/Flask code and extracts the schema. The Writer converts that into a human-readable guide. The Validator then cross-references the generated doc against the actual code signatures to ensure every required field is present. If the Validator finds a discrepancy, it sends the state back to the Analyst with a "correction" note.

Here is a simplified version of how I structured the LangGraph state and the routing logic:

from typing import TypedDict, List
from langgraph.graph import StateGraph, END

class DocState(TypedDict):
    code_snippet: str
    extracted_schema: dict
    draft_docs: str
    validation_errors: List[str]
    iterations: int

def analyst_node(state: DocState):
    # Logic to extract endpoints and types from code
    # Using Claude 3.5 Sonnet here for high precision
    return {"extracted_schema": {"endpoint": "/user", "params": ["id"]}, "iterations": state['iterations'] + 1}

def writer_node(state: DocState):
    # Converts schema to Markdown
    return {"draft_docs": "### User Endpoint\nFetches user data by ID."}

def validator_node(state: DocState):
    # Compares draft_docs vs code_snippet
    errors = [] # logic to detect missing params
    return {"validation_errors": errors}

# Define the graph
workflow = StateGraph(DocState)
workflow.add_node("analyst", analyst_node)
workflow.add_node("writer", writer_node)
workflow.add_node("validator", validator_node)

workflow.set_entry_point("analyst")
workflow.add_edge("analyst", "writer")
workflow.add_edge("writer", "validator")

# Conditional logic: if errors exist and we haven't looped 3 times, go back to analyst
workflow.add_conditional_edges(
    "validator",
    lambda x: "analyst" if x["validation_errors"] and x["iterations"] < 3 else END
)

app = workflow.compile()

Config tips for the prompt engineering part:

The Analyst Prompt: I found that telling the agent to "act as a compiler" works better than "act as a developer." I force it to output a strict JSON schema of the API first. If the JSON is wrong, the rest of the chain fails, which makes debugging way easier.

The Validator Prompt: This is the secret sauce. I give the Validator a "pedantic" persona. I tell it: "Your only goal is to find reasons why this documentation is misleading. Be ruthless." This prevents the "everything looks fine" bias that happens when one LLM reviews its own work.

Productivity Gains:

Zero-touch updates: I've hooked this into a GitHub Action. Whenever a file in /routes changes, LangGraph runs, generates the .md file, and creates a commit.

Consistency: No more "some endpoints have examples, some don't." The Writer node uses a strict template that it cannot deviate from.

The Gotchas:

Infinite Loops: If you don't implement an iterations counter in your state, the Analyst and Validator can get into a loop where they argue over a naming convention forever. Always cap your cycles at 3.

Context Window Bloat: If you feed an entire 2,000-line controller into the state, the Validator starts losing focus. I now split the code into individual function chunks before passing them into the graph.