Support semi-required parameters

[SimonHoiberg]

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 👇

[iliran11]

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

[SimonHoiberg]

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?