-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Required fields in HTTP API docs #3065
Comments
Thank you for the report! For the required type, it's kind of a mixed bag. Basically it makes most sense for a field to be required when it is expected in a request - so e.g. as a request parameter or request body:
because there, the client is informed: yo, this field is needed if you call this API endpoint. However, we also set However, for responses, I don't think it's that useful to have required responses as all fields will be set always anyways, except for some advanced use cases where I'm not sure how to handle this consistently throughout the code base. Do you have ideas or experience with this? /cc @vinckr because this might be helpful for context to you |
The issue is that when you build your own Hydra client application, you see all these fields in the responses that are optional, and if you need one of them in your logic, now you must always handle the case where that field might not be set. If the response fields are defined as required, though, you can just make the response parser strict and be confident that the field will always be set in the rest of the code base. If currently models are shared for requests and responses and the required fields differ, I guess the only way to handle this is to have separate Since the model will be the same across all responses, in the case of the oAuth2Client model we could have |
I see! That makes sense. It’s actually funny because in Golang the generator works the other way around. Required fields are there generated as pointers (e.g. |
Preflight checklist
Describe the bug
There are some inconsistencies in the Hydra HTTP API documentation regarding required fields.
consentRequest.skip
is optional, butloginRequest.skip
is required.consentRequest.subject
andlogoutRequest.subject
are optional, butloginRequest.subject
is required.consentRequest.client
andlogoutRequest.client
are optional, butloginRequest.client
is required.There may be more cases where the
required
attribute is missing in the documentation. Might be worth to check the type definitions.Reproducing the bug
Relevant log output
No response
Relevant configuration
No response
Version
v1.11.7
On which operating system are you observing this issue?
No response
In which environment are you deploying?
No response
Additional Context
No response
The text was updated successfully, but these errors were encountered: