Refresh openapi.yaml to reflect parameter capabilities

[KellyStathis]

Purpose

The purpose of this update is to refresh openapi.yaml (which powers https://support.datacite.org/reference/introduction) to reflect the full capabilities of our filter parameters for retrieving information, with a focus on the /dois endpoint. Better documentation of these parameters supports users in discovering their functionality.

closes: #1188

Approach

This update:

• Changes the type for the year date parameters (created, registered, published) to a string with a regex pattern because these parameters support multiple years, for example 2024,2023.
• Indicates when parameters allow multiple comma-separated values, either via the description or through an array with an enum.
  • Note that this should be accurate for /dois and others but I did not review all endpoints.
• Adds the publisher parameter to /dois.
• Adds the page[size] param where it was missing from provider-prefixes.
• Removes the value governmentAgency from member_types (this was a typo as it is one of our organization types).
• Removes the state parameter from /prefixes/totals because this is ignored.
• Refactors several enums and parameters and components for consistency and more efficient updates.
• Improves parameter descriptions for clarity and consistency.
• Adds example values for some parameters.

Open Questions and Pre-Merge TODOs

Learning

• Swagger docs for parameter serialization: https://swagger.io/docs/specification/serialization/

Types of changes

• Bug fix (non-breaking change which fixes an issue)

• New feature (non-breaking change which adds functionality)

• Breaking change (fix or feature that would cause existing functionality to change)

Reviewer, please remember our guidelines:

• Be humble in the language and feedback you give, ask don't tell.
• Consider using positive language as opposed to neutral when offering feedback. This is to avoid the negative bias that can occur with neutral language appearing negative.
• Offer suggestions on how to improve code e.g. simplification or expanding clarity.
• Ensure you give reasons for the changes you are proposing.

[KellyStathis]

I also opened #1230 with some more ideas for future work, particularly for DOI registration/updates.

[KellyStathis]

Thanks for the review @digitaldogsbody and @codycooperross! I refreshed the docs on ReadMe: https://support.datacite.org/reference/get_dois