Closed minpeter closed 2 months ago
@minpeter I understand your concern and agree that documentation generators should show the default as an error when a 2xx code is already present. According to the spec:
default - The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses.
And their example:
'200':
description: a pet to be returned
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
https://spec.openapis.org/oas/v3.1.0#responses-object
I think most code generators and other OpenAPI tools know that default
is treated special due to the spec explicitly calling it out. Huma is doing what is recommended by the spec here, so maybe the documentation generators should be updated to handle this case better? Like I'm struggling to understand what specific change should be made in Huma that will still be broadly compatible with the whole OpenAPI ecosystem of tools.
Thank you for your quick reply. After referring to the document above, I think that huma is creating the document in an excellent way.
in
huma.go
fileDue to the above code, the openapi docs field value of the default error response is defined as default. This does not seem to be a problem when using Stoplight Elements Docs because it is defined in the order [200, "default"], but in Scalar Docs, default is treated as a special value and arranged in the order ["default", 200].
Also, since the field name default looks like a response from a “successful” case at first glance, I think it would be a good idea to change it to another appropriate keyword, such as error or default error.