OctiAI

Categories

OpenAPI Reverse‑Engineer & Fix‑Plan Template

Convert controller/handler code, README and curl examples into a complete OpenAPI 3.1 spec plus ranked hypotheses, minimal patches and verification tests.

What You'll Get

How to Use

Provide the minimal, high-value inputs first

Start by supplying the router file, one controller/handler and one representative curl example. The template will infer the rest and explicitly list any additional files it needs — this speeds iteration and reduces noise.

Works Best With

Works best when you provide focused controller/route files plus docs or curl examples

Prompt Template

## Goal
- Infer a complete OpenAPI-style spec (paths, methods, request/response schemas, examples, auth requirements, error responses) and concise human-readable usage examples from provided controller/handler code, README, or curl examples. Detect and explain any mismatches between code and docs, and deliver engineering artifacts: ranked hypotheses for differences, diagnosis, minimal patch plan, patch guidance, and verification tests.

## Inputs
- Provide the repository slice or files to analyze: controller/handler source files, routing definitions, README or API docs, and representative curl examples. Indicate runtime/environment if relevant.
- Required metadata: programming language and framework, repository root path, and any non-goals or constraints (for example: "no refactor", "must not change public behavior", "prefer minimal diffs").
- If inputs are incomplete, the prompt must request only the minimal missing artifacts needed to infer the spec (e.g., router file, controller mapping, example request/response).
- Use these placeholders when invoking the prompt below: repository root → {{codebase_root}}, language/framework → {{language_framework}}, constraints → {{constraints}}, desired output format → {{desired_output_format}}.

## Prompt
You are an expert API reverse-engineer and API spec author. Using the provided source files, README, and curl examples reachable under {{codebase_root}} and knowing the codebase uses {{language_framework}}, do the following in a precise, engineering-grade way that supports automated pipelines.

1) Parse the code and examples to infer every exposed HTTP endpoint. For each endpoint, output:
   - path and HTTP method
   - authentication/authorization requirements
   - path/query/header/body parameters (names, types, required/optional)
   - request content-types and example payload(s)
   - response status codes and response body schemas with examples
   - error formats and possible error status codes
   - where in the repo each endpoint is implemented (file and handler/function name)

2) Produce a complete OpenAPI 3.1 spec (YAML preferred; if {{desired_output_format}} == json, produce JSON) that includes schemas, components, security schemes, examples, and error catalog. Mark any uncertain fields with x-uncertain: true and a brief reason.

3) While inferring the spec, detect any mismatches or ambiguities between code, README, and curl samples. For each mismatch, produce:
   - a short description
   - ranked root-cause hypotheses (why the mismatch exists)
   - a reproducible checklist to verify the issue locally

4) For each confirmed or likely mismatch/bug, produce a minimal patch plan that:
   - limits scope to minimal diffs (file and line ranges to change)
   - lists exact code edits or config changes (diff-style bullets)
   - includes acceptance criteria and risk checks
   - includes rollback instructions

5) Produce patch guidance: code snippets for the minimal changes, unit/integration test stubs to add, and any migration or release notes needed.

6) Provide a verification test checklist: concrete curl or HTTPie commands, expected status codes and responses, unit/integration test assertions, and automated CI checks to add.

7) Deliver a short human-readable usage guide with 3 example client requests and responses for the most important endpoints.

Constraints to respect from caller: {{constraints}}. Do not change public API behavior unless explicitly allowed. If you lack a file or example needed to complete any part, list the exact minimal file(s)/snippet(s) required and stop.

Produce outputs as structured sections and machine-consumable artifacts so they can be consumed by automation: OpenAPI YAML/JSON, per-endpoint mapping to source files, ranked hypotheses, reproduction checklist, minimal patch plan (with diff-like guidance), patch snippets, and verification tests.

Be explicit about assumptions and unknowns. Prefer conservative interpretation: when unsure, mark x-uncertain and provide the specific rationale and evidence lines from source files or examples.

## Output Format
Output:
1) Assumptions/Unknowns
2) Likely root causes (ranked)
3) Fix plan (steps)
4) Patch suggestions
5) Test/verification checklist

Produce:
- A complete OpenAPI 3.1 spec (YAML or JSON according to {{desired_output_format}}) under a header "OpenAPI Spec".
- "Endpoint → Source mapping" section with file paths and handler names.
- "Mismatches & Hypotheses" section with ranked causes and repro checklist.
- "Minimal Patch Plan" section with diff-style edits and acceptance criteria.
- "Patch Guidance" section with example code snippets and test stubs.
- "Verification Tests" section with concrete curl/HTTPie commands and expected outputs.
- Use explicit markers x-uncertain: true where fields are uncertain and include the evidence line(s) that caused the uncertainty.

## Guardrails
- Do not assume unseen files or endpoints; only infer what is present in supplied files and examples.
- Do not invent authentication schemes or error codes unless they are implied by code or examples; flag them as uncertain instead.
- Prefer minimal diffs; avoid scope creep or large refactors.
- If multiple plausible interpretations exist, list them, rank by likelihood, and provide the one-sentence reason for the ranking.
- Mark any generated spec items that are inferred (not explicit) with x-uncertain: true.
- Do not modify business logic; propose minimal changes that preserve behavior unless constraint allows otherwise.

## Examples
- Mini example mismatch & fix excerpt:
  - Mismatch: README shows POST /users returns 201 with { id }, but controller returns 200 with full user object.
  - Hypothesis (ranked #1): README outdated after controller change.
  - Minimal patch suggestion: update README example to 200 and example response to match controller; acceptance: clients still get id in response; risk check: backward-compatibility test verifies clients tolerant of extra fields.
  - Fix excerpt (diff-style):
    - README.md: change "Returns: 201" → "Returns: 200" and replace example JSON with controller response JSON.

Variables

Usage Notes

Not for

Do not include

OpenAPI Reverse‑Engineer & Fix‑Plan Template

Given source handlers, routing, README and curl examples, infer every exposed endpoint and produce a complete OpenAPI 3.1 spec (YAML or JSON), detect mismatches, and output minimal, testable patch plans and verification checks.

Turn this into a working asset in minutes.

Import into Workspace to auto-fill variables, adapt output style, and iterate with OctiAI's prompt editor.

What you'll get

Output format

Markdown

Best used when

Avoid when

Sign in to save, like, or rate this prompt.

Made for

What to fill in

Use the guidance below to complete each placeholder with the right level of detail.

Codebase Root

Provide the key details needed for this variable.

Language Framework

Provide the key details needed for this variable.

Constraints

Provide the key details needed for this variable.

Desired Output Format

Provide the key details needed for this variable.

Rules

Canonical Examples

Input: Node.js + Express repo at /repo/users-service. Provided files: controllers/users.js, routes/usersRoutes.js, README.md (contains curl example for POST /users), package.json. Constraints: do not change public behavior. desired_output_format: yaml

Loading result...

Failed to load output.

OpenAPI Spec (YAML) with POST /users and GET /users/{id}; README vs controller status-code mismatch flagged; minimal patch plan to update README and add unit test stubs.

Why it works: Small, focused controller + route files let the prompt fully infer exposed endpoints and compare README/curl examples to handler behavior. The constraint to avoid changing public behavior forces generating doc fixes or minimal compatibility patches.

Input: Python Flask microservice at /repo/items-api. Provided files: app.py (Flask routes), services/item_service.py (business logic), docs/api.md (contains curl examples for GET /items and POST /items), but no schema/model file. Constraints: prefer minimal diffs; desired_output_format: json

Loading result...

Failed to load output.

OpenAPI Spec (JSON) for GET /items and POST /items; highlights missing Item schema and request validation; proposes doc update and small test additions.

Why it works: Flask route decorators give clear mapping from URL to handlers; provided docs + examples allow building a usable OpenAPI JSON. Missing models require marking uncertainties and requesting minimal missing snippets if needed.

Works Best With

Works best when you provide focused controller/route files plus docs or curl examples