[Schema Inaccuracy] "GET /repos/{owner}/{repo}/issues" - incorrect schema for milestone parameter

[gr2m]

Follow up to WordPress/gutenberg#29043 (comment) /cc @ockham

Schema Inaccuracy

      - name: milestone
        description: If an `integer` is passed, it should refer to a milestone by
          its `number` field. If the string `*` is passed, issues with any milestone
          are accepted. If the string `none` is passed, issues without milestones
          are returned.
        in: query
        required: false
        schema:
          type: string

Expected

The description says that the milestone parameter can also be a number

If an integer is passed, it should refer to a milestone by its number field. If the string * is passed, issues with any milestone are accepted. If the string none is passed, issues without milestones are returned.

Reproduction Steps

n/a

[mattpage]

@gr2m - What this is saying is that the milestone query param can contain a string representation of an integer, e.g., "42". But because it also may have the value * or none its type is string.

[gr2m]

I'd expect that the schema would be a oneOf:

• number
• string enum with the permitted values * and none