Parameters description added to incorrect level about huma HOT 3 CLOSED

Oh, actually I just tried this in https://editor-next.swagger.io/ and you are right, SwaggerUI doesn't show it. Maybe we need to add it in both places for the best compatibility... 🤔

from huma.

Yes, right, for JSON Schema it required under schema object but it doesn't work for swaggerui though. I tested with stoplight though and it shows description. But I guess as you said, adding at both places will definitely help.

from huma.

@NishadVadgama thanks for opening the issue! This is actually allowed in JSON Schema, see https://json-schema.org/draft/2020-12/json-schema-validation#name-title-and-description:

9.1. "title" and "description"
The value of both of these keywords MUST be a string.

Both of these keywords can be used to decorate a user interface with information about the data produced by this user interface. A title will preferably be short, whereas a description will provide explanation about the purpose of the instance described by this schema.

Huma uses the schema description on purpose so that tools which use just the schema can still get description information.

Are you running into any problem with this behavior? I believe all the popular documentation generators and SDK generators will use the schema description when available. Let me know if that's not the case and we can figure out what to do about it.

from huma.