Openapi To Python Lungo

Step 4 - Reconcile router.py

For each operation under this tag:

1. Compute the expected handler from the OpenAPI operation:

   • Function name: operationId converted to snake_case. If operationId is missing, derive a stable name from <method>_<path> and warn the user that adding operationId is preferred.
   • Decorator: @router.<method>(<path>, response_model=<dto_or_type>, status_code=<status>, summary="<summary>"). Omit response_model / status_code only when the operation declares no non-default 2xx response or no schema.
   • Parameters:
     • Path params: Annotated[<py_type>, Path(<constraints>)].
     • Query params: Annotated[<py_type>, Query(<constraints>)] with the OpenAPI default if present.
     • Request body: typed parameter using the body schema's DTO.
   • Return type annotation: the response DTO (or RedirectResponse, StreamingResponse, etc. for non-JSON responses).

2. If the function does not exist, create it with the signature above and a stub body:

   raise HTTPException(status_code=501, detail="Not implemented")

   Add a one-line docstring summarizing the method and path.

3. If the function exists:

   • Update its decorator and signature in place to match the spec.
   • Preserve the handler body verbatim.
   • Preserve any decorator-unrelated import the user added.

4. After processing all spec operations, look for handler functions inside create_<tag_snake>_router() that no longer correspond to any operation. Do not delete them silently - emit a warning of the form:

   Stale handler: <function_name> is no longer in the OpenAPI spec for tag '<tag>'. Remove it manually if intentional.

5. Make sure the APIRouter is constructed with tags=["<tag>"] and that create_<tag_snake>_router() returns it. Preserve every other argument already passed to APIRouter(...). When regenerating an existing router, the OpenAPI document does not describe router-level construction options, so anything the user put on the constructor must survive untouched:

   • dependencies=[...] - router-level dependencies (e.g. an auth gate). Keep the full list and the imports backing it. This rule is general: treat any value found in dependencies= the same way, regardless of which callable it wraps.
   • prefix=, responses=, default_response_class=, deprecated=, and any other keyword arguments - keep them verbatim.

   Only add tags=[<tag>] if it is missing, and only reconcile tags itself; never drop, reorder, or rewrite the user's other constructor arguments. If you cannot safely merge tags while preserving an existing argument, stop and ask the user.

   # If the existing code looks like this, keep `dependencies=` (and its import) on regen:
   from api.<tag_snake>.auth import require_workflow_api_key  # example dependency - preserve whatever import is present
   
   router = APIRouter(
       tags=[_TAG],
       dependencies=[Depends(require_workflow_api_key)],  # example only - preserve any dependencies found
   )

See reference.md § Router templates for concrete snippets.

Step 5 - Generate tests

Ensure the directory tests/unit/openapi/ exists. For each tag, generate (or refresh) two files. File names are not load-bearing; the convention below uses <tag_snake> and is recommended:

• tests/unit/openapi/test_<tag_snake>_openapi_spec.py - validates the resolved OpenAPI document with openapi_spec_validator.
• tests/unit/openapi/test_<tag_snake>_openapi_routes_match_app.py - builds a minimal FastAPI app via create_<tag_snake>_router() and asserts that the (path, METHOD) set from app.openapi() equals the set extracted from the resolved OpenAPI spec.

For the agentic-workflows tag, also keep (do not regenerate from templates):

• tests/unit/openapi/openapi_spec_helpers.py - load resolved spec; collect declared vs implemented status codes.
• tests/unit/openapi/test_agentic_workflow_openapi_status_codes.py - global security, every operation declares responses, implementation statuses ⊆ OpenAPI, and error status codes $ref the matching components/responses name (404 → NotFound, 422 → UnprocessableEntity, etc.; see ERROR_STATUS_TO_RESPONSE_COMPONENT in helpers).

When adding a new tag with non-trivial error surfaces, add matching helpers/tests using the agentic-workflows pair as a pattern; see reference.md § Status-code conformance.

Both standard tests resolve schema/openapi/openapi.yaml via prance and use the same _HTTP_METHODS filter shown in reference.md § Test templates. They must not assume any specific endpoint names - they compare full sets.

Step 6 - Run tests and linter

Run from coffeeAGNTCY/coffee_agents/lungo/:

uv run pytest tests/unit/openapi/ tests/unit/api/ -q

If integration tests reference the affected tag (for example tests/integration/... files matching the tag), run them too. Then run the project's standard linter / formatter (ruff, make lint, etc., as configured for the project) on all touched files. Fix any errors before finishing.

Validate workflow

Use this when the user has hand-edited router.py or dtos.py and wants confirmation that the spec, code, and tests are still consistent.

- [ ] 1. Resolve the OpenAPI spec (prance) and confirm it validates
- [ ] 2. Diff (path, METHOD) sets: spec vs FastAPI app
- [ ] 3. For each spec operation, confirm the handler signature matches
- [ ] 4. Confirm dtos.py would be regenerated identically
- [ ] 5. Run the OpenAPI and router tests (includes OpenAPI status conformance for agentic-workflows)

Step 1 - Resolve and validate the spec

Use prance.ResolvingParser plus openapi_spec_validator.validate(...). A failure here means the spec itself is broken; report it and stop.

Step 2 - Path/method diff

Build the minimal FastAPI app exactly as in the generated test_<tag_snake>_openapi_routes_match_app.py, then compute the symmetric difference between the spec and app (path, METHOD) sets. Report:

• Only in spec: ... - handlers missing from router.py.
• Only in app: ... - extra handlers not in the spec (likely stale).

Step 3 - Per-operation signature check

For every spec operation, confirm:

• the handler exists,
• its decorator matches (response_model, status_code, summary, path, method),
• the parameter list (path, query, body) and types match the spec.

Report mismatches with the operation id and a one-line diff.

Step 4 - DTO drift check

Run the regeneration logic from step 3 of the generate workflow against an in-memory buffer and diff it against the on-disk dtos.py. If they differ, the user has either edited dtos.py by hand or the spec changed without regeneration. Recommend re-running the generate workflow.

Step 5 - Run the tests

Run the same tests as in the generate workflow. They are the authoritative validation.

When to ask the user

Stop and ask the user before doing any of:

• deleting or renaming a public symbol from dtos.py that is imported elsewhere in the project,
• removing a stale handler from router.py (always recommend, never auto-delete),
• changing an existing handler body to satisfy a signature change (only the signature is yours; body changes belong to the user).

Additional resources

• reference.md - OpenAPI → Pydantic mapping rules, router templates, and test templates with concrete snippets.