---
title: "FastAPI operationId path tails leaked into generated command names"
date: 2026-05-22
category: logic-errors
module: internal/openapi
problem_type: logic_error
component: tooling
symptoms:
  - "FastAPI default operationIds generated command names like `list-api-get` and `create-api-generate-post`."
  - "Readable function prefixes and generated path tails were treated as one operationId-derived command name."
  - "Parser-only coverage would not prove generated CLI and MCP command names stayed readable."
root_cause: logic_error
resolution_type: code_fix
severity: medium
related_components:
  - internal/generator
  - testdata/golden
tags:
  - openapi-parser
  - operationid
  - fastapi
  - command-naming
  - golden-harness
---

# FastAPI operationId path tails leaked into generated command names

## Problem

FastAPI's default OpenAPI operationId shape is `<function_name>_<path_segments>_<method>`. The parser's existing framework-generated operationId detector recognized API Platform and Symfony-style concatenated path tokens, but not FastAPI's suffix shape. As a result, FastAPI specs generated commands with the machine path tail still attached, such as `quotes list-api-get`, `quotes create-api-generate-post`, and `health check-get`.

## Symptoms

- `list_quotes_api_quotes_get` became `quotes list-api-get` instead of a readable list command.
- `create_quote_api_quotes_generate_post` became `quotes create-api-generate-post`.
- `get_quote_api_quotes__quote_id__get` retained the generated `api` and HTTP method tokens.
- Single-path helpers such as `health_check_health_get` kept the trailing method token.

## What Didn't Work

- **Only skipping the whole operationId for every FastAPI match.** This fixed the `api-...-method` tail, but it renamed readable non-CRUD prefixes like `health_check` to generic method-derived names.
- **Treating every CRUD-looking FastAPI prefix as disposable.** This made POST-based read operations look mutating. For example, a default FastAPI operationId like `list_items_api_items_search_post` should keep a read-shaped command name instead of becoming `create`.
- **Reusing the expanded FastAPI HTTP-method helper in the older API Platform detector.** That accidentally broadened the legacy detector to accept bare `_get`, creating false positives for hand-curated names ending in `Get`.

## Solution

Handle FastAPI as its own operationId shape:

1. Detect operationIds whose token suffix exactly matches the path tokens plus the HTTP method.
2. Split the function-name prefix from the generated path/method tail.
3. Preserve useful function prefixes when they carry command intent.
4. Fall back to method/path names only for cases where the function prefix is redundant and method-aligned, such as `create_*` on POST, `update_*` on PATCH or PUT, `delete_*` on DELETE, and the common `read_*` GET convention.
5. Keep the API Platform detector's original suffix policy separate so FastAPI support does not broaden older false-positive boundaries.

The fix lives in `internal/openapi/parser.go` near `resolveEndpointName` and `isFrameworkAutoGeneratedOperationID`. It adds FastAPI-specific helpers for suffix detection and prefix-derived endpoint naming while leaving the existing concatenated-token detector intact.

Coverage includes:

- Parser tests for FastAPI list, create, get, update, delete, health check, `read_*`, POST-based read, HEAD, and OPTIONS shapes.
- A negative detector test for a hand-curated camelCase id ending in `Get`.
- A golden case, `generate-fastapi-operationids`, that locks the generated CLI and MCP output for FastAPI-shaped ids.

## Why This Works

FastAPI's generated path tail is deterministic and redundant with the OpenAPI path and method. The useful signal, when present, is in the function-name prefix. Separating those two parts prevents generated infrastructure tokens from leaking into CLI names while still preserving domain intent for non-CRUD or read-shaped function names.

Keeping FastAPI detection separate from the existing API Platform detector matters because the two frameworks encode different signals. API Platform's detector relies on concatenated adjacent path segments and a narrow suffix set. FastAPI's detector relies on an exact path-token suffix. Merging those policies makes false positives more likely.

## Prevention

- Add a golden fixture when parser changes alter deterministic generated command names, help, or MCP tools. A passing golden verify on existing cases does not prove the new naming shape is covered.
- Keep framework-specific operationId detectors separate unless their false-positive boundaries are identical.
- For generated operationIds that combine readable and machine-generated parts, preserve the readable prefix only after proving the suffix is derivable from the path and method.
- Include at least one negative hand-curated operationId near every new detector boundary.

## Related Issues

- Issue #1488
- Prior pattern: `docs/solutions/logic-errors/openapi-parser-missing-x-mcp-extension-support-2026-05-08.md`
