What this error means
openapi-generator-cli validate -i openapi.yaml runs your spec through the Java swagger-parser before doing anything else, and generate runs the same check. The message format is a dotted path into the document:
Validating spec (openapi.yaml)
Errors:
- attribute paths.'/users'(get).responses is missingRead it inside out: the get operation on the /users path is missing its responses attribute. The OpenAPI specification makes responses the one required field on every operation, because without it a consumer knows nothing about what comes back.
Why openapi-generator emits it
The generator needs responses to do its job. Return types in generated clients, response models in server stubs, and status code handling all come from the responses object. An operation without one is not just invalid; it is ungeneratable. So the validator treats it as a hard error, not a warning. It usually shows up on draft endpoints that were sketched and committed before the response shape was decided.
openapi: 3.0.3
info:
title: Example API
version: "1.0"
paths:
/users:
get:
summary: List users
# no responses objectopenapi: 3.0.3
info:
title: Example API
version: "1.0"
paths:
/users:
get:
summary: List users
responses:
'200':
description: A list of usersA status code plus a description is the floor. For a useful generated client, add a content map with a schema so the generator can produce a typed return value instead of void.
You will see the same attribute ... is missing format for other required fields: attribute info is missing, attribute paths is missing, and attribute info.version is missing all come from the same validator and all point at the missing key by path.
How to catch it earlier
Because generate refuses to run on an invalid spec, this error tends to surface at the worst moment: when someone else tries to build a client from your spec. Validate at edit time instead. The free OpenAPI validator flags operations without responses as you paste, and the OpenAPI linter adds quality checks like requiring a default or error response, not just any response. Both catch the draft-endpoint case before it lands in the repo.
Frequently asked questions
How do I read the paths.'/users'(get).responses format?
It is a dotted path into your document: the paths section, the /users path, the get operation, its responses attribute. The parenthesized segment is always the HTTP method.
Can I just skip validation?
generate accepts --skip-validate-spec, and it will run. But the generator has no return type to work with, so the affected operations come out as void or Object. A two-line responses block is the better trade.
What is the minimum valid responses object?
One status code with a description: responses: { '200': { description: OK } }. Description is itself required on every response, so an empty status code mapping still fails.