The default error response field value in openapi docs is "DEFAULT"

[minpeter]

currently	suggestion

in huma.gofile

if len(op.Responses) <= 1 && len(op.Errors) == 0 {
// No errors are defined, so set a default response.
op.Responses["default"] = &Response{
	Description: "Error",
	Content: map[string]*MediaType{
		errContentType: {
			Schema: errSchema,
		},
	},
}
}

Due 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.

[danielgtaylor]

@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.

[minpeter]

Thank you for your quick reply.
After referring to the document above, I think that huma is creating the document in an excellent way.