openai / openai/openai-openapi
Make `Responses` tagging complete and consistent across the OpenAPI document
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 2.5k
- Forks
- 527
- Avg merge
- 1h 46m
- Merged PRs (30d)
- 2
Description
Responses API operations are not tagged consistently in openapi.yaml.
Most Responses API operations use:
tags:
- Responses
However:
Responsesis not declared in the root-leveltagsarray.- Some Responses API operations do not contain the
Responsesoperation tag.
This makes tag-based filtering incomplete and can cause documentation tools to organize the undeclared tag inconsistently.
Affected operations
The following stable operations have x-oaiMeta.group: responses but no tags property:
POST /responses/input_tokens
POST /responses/compact
The corresponding beta path entries also appear to be missing the tag:
POST /responses/input_tokens?beta=true
POST /responses/compact?beta=true
By comparison, the other Responses API operations use:
tags:
- Responses
Root-level tag declaration
The document declares tags such as Chat, Audio, and Embeddings in the root-level tags array, but does not declare Responses, even though many operations use that tag.
A declaration similar to the following would make the tag catalog complete:
tags:
- name: Responses
description: Create and manage model responses.
Why this matters
Consumers commonly use operation tags to:
- Generate API-specific documentation.
- Generate partial clients.
- Group operations in API explorers.
- Extract only the endpoints belonging to a particular API family.
- Reduce the size of the specification before processing it.
At present, filtering for operations tagged Responses silently excludes the input-token-counting and compaction endpoints.
Minimal reproduction
import yaml
with open("openapi.yaml", encoding="utf-8") as file:
spec = yaml.safe_load(file)
declared_tags = {
tag["name"]
for tag in spec.get("tags", [])
}
used_tags = set()
untagged_response_operations = []
http_methods = {
"get", "post", "put", "patch",
"delete", "head", "options", "trace",
}
for path, path_item in spec.get("paths", {}).items():
for method, operation in path_item.items():
if method.lower() not in http_methods:
continue
tags = operation.get("tags", [])
used_tags.update(tags)
group = operation.get("x-oaiMeta", {}).get("group")
if group == "responses" and "Responses" not in tags:
untagged_response_operations.append(
f"{method.upper()} {path}"
)
print("Responses declared:", "Responses" in declared_tags)
print("Responses used:", "Responses" in used_tags)
print("Untagged Responses operations:")
print("\n".join(untagged_response_operations))
Current behavior
The script reports that:
Responsesis used but not declared.- Some operations in the
responsesmetadata group do not use theResponsestag.
Expected behavior
Responsesis included in the root-leveltagsarray.- Every Responses API operation includes
tags: [Responses]. - Stable and beta variants follow the same tagging convention.
Suggested acceptance criteria
- Add a root-level declaration for the
Responsestag. - Add the
Responsestag to every operation whosex-oaiMeta.groupisresponses. - Add a CI check ensuring operation tags and
x-oaiMeta.groupvalues remain consistent. - Add a CI check warning when an operation uses an undeclared root-level tag.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in openapi.yaml by comparing the root-level tags array with operations whose x-oaiMeta.group is responses, especially the stable and beta input_tokens and compact paths. Run the Python reproduction from the issue to verify undeclared and untagged operations. Done means every Responses operation is tagged, Responses is declared at the root, and CI checks the stated tag consistency rules.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100