Code Comment API Documentation Extraction Prompt Template

This prompt is designed for developer tools engineers and platform teams who need to automate the conversion of source code comments into a structured, machine-readable API documentation catalog. The primary job-to-be-done is transforming raw source files containing JSDoc, Python docstrings, JavaDoc, or inline annotations into a consistent JSON array of endpoints, parameters, return types, and usage examples. This output is intended for direct ingestion by documentation generators, API portals, or internal service catalogs, eliminating the manual drift between code and docs. The ideal user is an engineer building an internal developer portal, a CI/CD pipeline maintainer, or a technical writer managing a docs-as-code workflow who needs a reliable, typed extraction layer that can handle the messy reality of incomplete or inconsistent comment formats.

You should use this prompt when you have a repository of source code text and require a structured extraction that normalizes disparate comment styles into a single schema. The prompt assumes the input is raw source code text, not a pre-parsed Abstract Syntax Tree (AST) or a compiled comment tree. This makes it suitable for lightweight pipeline stages where you are processing code as text before or after a parser runs. It is particularly effective for handling legacy codebases where comments are non-standard, or for aggregating documentation across polyglot microservice environments. However, do not use this prompt for generating prose tutorials, architectural decision records, or natural-language summaries of entire codebases. It is a structured extraction tool, not a narrative generator. For high-risk or security-sensitive APIs, you must implement a human review step to validate the extracted records before they are published, as the model may misinterpret authorization scopes or deprecated flags from comments alone.

Before integrating this prompt, ensure your pipeline can handle the required inputs: the raw source code text and a defined output schema. The prompt works best when you provide a clear [OUTPUT_SCHEMA] that matches your downstream ingestion contract, such as a specific JSON structure for your API catalog. If your source code contains no comments, or only auto-generated boilerplate, the extraction will produce sparse or empty records, which is expected behavior. The next step is to wire this prompt into an application harness that validates the JSON output, retries on malformed responses, and logs extraction confidence for auditability. Avoid using this prompt as a one-off utility; its value compounds when it is part of a repeatable CI/CD pipeline that keeps documentation in sync with every commit.

This prompt template is designed to extract structured API endpoint records from source code comments in formats like JSDoc, Python docstrings, or inline annotations. It expects a raw code block as input and produces a typed JSON array of endpoint objects, each containing method, path, parameters, return types, and examples. The template uses square-bracket placeholders that you must replace before sending to the model—these control the input source, output schema, extraction constraints, and risk tolerance.

textCopy
You are an API documentation extraction engine. Your job is to read source code comments and produce a structured JSON array of API endpoint records.

## INPUT
[CODE_BLOCK]

## OUTPUT SCHEMA
Return a JSON array of endpoint objects. Each object must follow this schema exactly:
{
  "endpoint_id": "string (unique slug derived from method+path)",
  "method": "GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS",
  "path": "string (the route pattern, e.g. /users/{id})",
  "summary": "string (one-line description of what the endpoint does)",
  "description": "string (longer explanation, may include markdown)",
  "parameters": [
    {
      "name": "string",
      "location": "path|query|header|body|cookie",
      "type": "string (JSON Schema type or language type)",
      "required": true|false,
      "description": "string",
      "default": "string or null",
      "example": "string or null"
    }
  ],
  "request_body": {
    "content_type": "string (e.g. application/json)",
    "schema": "string (type description or JSON Schema snippet)",
    "required": true|false,
    "example": "string or null"
  } | null,
  "responses": [
    {
      "status_code": 200,
      "description": "string",
      "schema": "string (type description or JSON Schema snippet)",
      "example": "string or null"
    }
  ],
  "auth_required": true|false,
  "deprecated": true|false,
  "tags": ["string"],
  "source_comment_type": "jsdoc|docstring|inline|block|unknown",
  "extraction_confidence": "high|medium|low",
  "extraction_notes": ["string (any ambiguities, missing fields, or assumptions made)"]
}

## CONSTRAINTS
[CONSTRAINTS]

## EXAMPLES
[EXAMPLES]

## INSTRUCTIONS
1. Parse all comments in the provided code block, regardless of comment style.
2. Identify every documented API endpoint. If a comment block describes an endpoint but is missing the method or path annotation, infer it from surrounding code context if possible and flag it in extraction_notes.
3. For each parameter, extract the name, type, location, required flag, description, default value, and example if present. If a parameter is mentioned in prose but not formally annotated, include it with extraction_confidence set to "low" and note the inference.
4. For request bodies, extract the content type, schema description, required flag, and example. If the body schema is defined in a separate type or interface, include a reference note rather than expanding it inline.
5. For responses, extract every documented status code with its description, schema, and example. If only a success response is documented, include it and note that other status codes are undocumented.
6. Detect deprecation notices, version tags, and authentication requirements from comments and annotations.
7. Set extraction_confidence to "high" only when all expected fields are explicitly present. Use "medium" when some fields required inference. Use "low" when the comment block is sparse or ambiguous.
8. Never fabricate endpoints, parameters, or examples that are not present in the source. If a field is missing, omit it or set it to null as appropriate.
9. If the code block contains no API documentation comments, return an empty array.
10. If [RISK_LEVEL] is "high", include a human_review_required boolean for any endpoint where extraction_confidence is "low" or where auth_required is true but the auth mechanism is unclear.

Return ONLY the JSON array. No markdown fences, no commentary.

To adapt this template, replace [CODE_BLOCK] with the raw source code you want to extract from. Replace [CONSTRAINTS] with any additional rules—for example, "ignore private endpoints marked with @internal" or "only extract endpoints tagged @api-public." Replace [EXAMPLES] with one or two few-shot examples showing a code comment and its expected JSON output to anchor the model's behavior. If your use case is high-risk (generating customer-facing docs, compliance-sensitive APIs), set [RISK_LEVEL] to "high" to enable the human review flag. Always validate the output JSON against your schema before ingestion—missing fields, type mismatches, or hallucinated endpoints are the most common failure modes. For production pipelines, pair this prompt with a validation step that checks required fields, enum values, and path format consistency before the extracted records enter your API catalog.

This prompt is designed to be embedded in a developer tool or CI/CD pipeline that scans source files, extracts structured API documentation from comments, and writes the results to a documentation database or OpenAPI spec. The harness must handle file I/O, chunking, model invocation, output validation, and error recovery. The prompt itself is a single step in a larger workflow that includes file discovery, comment block isolation, and post-processing of the extracted records.

Implement a validation layer that checks every extracted record against a JSON Schema before accepting it. Required fields include endpoint, method, parameters, and return_type. Reject records where endpoint is missing or method is not a recognized HTTP verb. For optional fields like examples and deprecated, apply default values ([] and false respectively) when absent. Log validation failures with the source file path and the raw model output for debugging. If more than 10% of records from a single file fail validation, halt processing for that file and flag it for human review—this often indicates a malformed comment block or a model drift issue.

Use a retry loop with a maximum of two retries for validation failures. On retry, include the validation error message and the original comment block in the prompt context so the model can correct its output. If the retry also fails, write the raw output to a dead-letter queue and continue processing other files. For model selection, prefer a model with strong JSON mode and code understanding capabilities. Set temperature to 0.0 for deterministic extraction. If processing large codebases, batch files into groups of 50-100 and run extraction in parallel, but rate-limit API calls to avoid throttling. Store extracted records in a versioned documentation store keyed by file_path + endpoint so subsequent runs can diff changes and detect deprecated or removed endpoints.