Support semi-required parameters
SimonHoiberg opened this issue · 2 comments
Is your feature request related to a problem? Please describe.
For multiple endpoints, there is a constraint that either user_id
or screen_name
should be provided.
An example can be found in this bug report.
On the Twitter Documentation, both user_id
and screen_name
is flagged as required
, where in fact, only one of them is required.
This is also stated in the description.
I will call these types of parameters semi-required in respect to another parameter.
Describe the solution you'd like
Back in a very early version, I introduced a type UserIdOrScreenName
that was able to make exactly this inference.
See the implementation here
This type got discarded due to the introduction of the generators.
I suggest that we reintroduce this type and introduce a new syntax in the twitter-api-spec.yml
file, that indicates semi-required fields.
A suggestion could be the following:
parameters:
- name: user_id
description: ....
required: !screen_name # <- Conditional requirement
type: number
- name: screen_name
description: ....
required: !user_id # <- Conditional requirement
type: string
Describe alternatives you've considered
I think the above suggestion would be feasible, however, we could also implement solutions inspired by big projects, to make the syntax more familiar.
Here is a couple of examples of conditionals in YAML specifications:
https://docs.ansible.com/ansible/latest/user_guide/playbooks_conditionals.html
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html
Additional context
Let's discuss a good solution in this issue 👇
Hi,
I think the suggested syntax is generic and flexible - gives you a room for combinations. But can also produce complex interfaces - and that might cost in implementation time.
I have another less-generic and less-complex suggestion IMO.
The assumption is a field can appear only once in the one-of-parameters
section:
parameters:
- name: force_login
description: Forces the user to enter their credentials to ensure the correct users account is authorized.
required: false
type: boolean
- name: x
description: Some description
required: false
type: string
one-of-parameters:
- identification-options:
- name: user_id
description: xxx
type: number
- name: screen_name
description: yyy
type: string
I think your suggestion is great for more complex scenarios.
Currently, I'm afraid to add further verbosity, since the yml spec files are already quite extensive.
I think a simple conditional statement will cover this use-case for now, and if we see the need for more complex conditional parameters (as the v2 endpoints develop), we will re-address this issue.
What do you think?