Clean up openapi.yaml

[KellyStathis]

Purpose

Make our OpenAPI specification more accurate, with particular attention to response structures.

closes: #1230

Approach

Change summary

• Differentiate list and singleton responses, including the data/meta/links structure for lists.
• For list responses with "meta", specify which properties are available within the "meta" object.
• Update the components for the Activity, Client, ClientPrefix, Event, Prefix, Provider, ProviderPrefix, and Report objects to reflect their contents.
• Differentiate between authenticated and unauthenticated responses for clients and providers.
• For DOI components, differentiate between list and singleton/detail responses using DoiListItem and DoiDetailItem. This was formerly done for the attributes within the item, via DoisAttributes (for the attributes in the list response) and DoiAttribute (for the attributes in the (detailed)singleton response).
• Incorporate or refactor components for reused enums and components of response structures.
• Update descriptions and example values.

Open Questions and Pre-Merge TODOs

For the reviewer, I'd appreciate a quick check on the following endpoints' documentation. These are among the most important for our users, and where I made the most changes to the spec in this PR. These links are a preview of the changes from this branch:

• POST /dois: https://support.datacite.org/reference/post_dois-1
• PUT /dois{id}: https://support.datacite.org/reference/put_dois-id-1
• GET /clients{id}: https://support.datacite.org/reference/get_clients-id-1 response structure
• GET /providers{id}:https://support.datacite.org/reference/get_providers-id-1 response structure

Post-merge tasks for @KellyStathis :

• remove the hidden test endpoint from readme
• review which support docs are linked from each readme API reference page; this lives outside openapi.yaml. specifically more detail could be included for clients, providers, and activities to explain what these are.

Learning

ideas for future work: #1235

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.

[codycooperross]

I added fixes for a typo or two. This looks great! The inline schema documentation is really helpful. I skimmed the mentioned endpoint documentation.