docs: add operation descriptions and typed error bodies to the OpenAPI spec

[shirgoldbird]

Spec-only changes, from an audit of how machine-readable our API surface is. No behavior claims beyond what the live API already does, but points 2 and 3 assert things about the API's error contract, so they want a review from someone who owns that contract.

1. description on 27 operations

27 of 62 operations had only a summary. Anything that generates a client or a tool definition from the spec had nothing to work from for those endpoints.

2. A JSON schema on every error response

141 error responses declared only a description and no content. Reading the spec, a client could not tell that DeepL returns a parseable JSON body on an error at all.

Fixed at the source rather than per-operation: 6 shared components/responses (InternalServerError, ServiceUnavailable, ForbiddenGlossaries, URITooLong, UnsupportedMediaTypeGlossaries, QuotaExceededGlossaries) now declare application/json, and two inline 415s now $ref the shared UnsupportedMediaType response instead of duplicating it.

3. InfrastructureErrorResponse, with oneOf on 414/500/503/504

While probing the live API I found the edge layer returns a different error shape than the application:

$ curl 'https://api.deepl.com/v2/languages?type=<9000 chars>'
HTTP/2 502
{"error": {"message": "Bad Gateway."}}

versus the application's {"message": "..."}. So declaring only ErrorResponse on the codes that either layer can produce would have been wrong. Those four now use oneOf: [ErrorResponse, InfrastructureErrorResponse].

Questions for the reviewer

1. Is oneOf on 414/500/503/504 the right split? I mapped the two shapes by observation. Someone who knows which layer serves which status code should confirm, especially for 503/504.
2. HTTP 502 is undocumented. It appears in no operation's responses, but the edge clearly returns it. Adding it across 62 operations is a call on what the edge guarantees, so I left it out.
3. New operation descriptions are worth a skim for accuracy, particularly the Admin API and Style Rules ones.
4. POST /v2/glossaries (v2) got "For new integrations we recommend POST /v3/glossaries" rather than any deprecation wording, per CLAUDE.md. Flagging in case a stronger signal is wanted.

Verification

• openapi.json regenerated with yq -o=json, verified structurally identical to the YAML.
• mint broken-links --check-anchors: 44 findings before and after, all pre-existing (pipeline/drafts/ and existing anchor drift).
• mint dev: all API reference pages still render, new descriptions confirmed on the rendered pages.

Note

openapi.yaml also lives in the openapi repo. These changes still need porting there.

🤖 Generated with Claude Code