Initial update to a couple of Management API endpoints

[OwainWilliams]

After an initial conversation on #20186 I've started working on adding Summary and Descriptions to the Management API Swagger docs.

This is an update to the Culture and DocumentVersion endpoints. Started with a couple of the smaller endpoints so that I can make updates if required and get an idea of what is being looked for.

[github-actions]

Hi there @OwainWilliams, thank you for this contribution! 👍

While we wait for one of the Core Collaborators team to have a look at your work, we wanted to let you know about that we have a checklist for some of the things we will consider during review:

• It's clear what problem this is solving, there's a connected issue or a description of what the changes do and how to test them
• The automated tests all pass (see "Checks" tab on this PR)
• The level of security for this contribution is the same or improved
• The level of performance for this contribution is the same or improved
• Avoids creating breaking changes; note that behavioral changes might also be perceived as breaking
• If this is a new feature, Umbraco HQ provided guidance on the implementation beforehand
• 💡 The contribution looks original and the contributor is presumably allowed to share it

Don't worry if you got something wrong. We like to think of a pull request as the start of a conversation, we're happy to provide guidance on improving your contribution.

If you realize that you might want to make some changes then you can do that by adding new commits to the branch you created for this work and pushing new commits. They should then automatically show up as updates to this pull request.

Thanks, from your friendly Umbraco GitHub bot 🤖 🙂

[Copilot]

Pull Request Overview

Adds EndpointSummary and EndpointDescription attributes to selected Management API endpoints to improve Swagger/OpenAPI documentation.

• Adds summaries/descriptions to DocumentVersion endpoints (list, get-by-id, rollback, set prevent-cleanup).
• Adds summaries/descriptions to Culture list endpoint.

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/Umbraco.Cms.Api.Management/Controllers/DocumentVersion/UpdatePreventCleanupDocumentVersionController.cs	Adds summary/description explaining the prevent-cleanup flag operation.
src/Umbraco.Cms.Api.Management/Controllers/DocumentVersion/RollbackDocumentVersionController.cs	Adds summary/description for rolling back a document to a specific version.
src/Umbraco.Cms.Api.Management/Controllers/DocumentVersion/ByKeyDocumentVersionController.cs	Adds summary/description for fetching a specific document version by ID.
src/Umbraco.Cms.Api.Management/Controllers/DocumentVersion/AllDocumentVersionController.cs	Adds summary/description for listing versions of a document (paged).
src/Umbraco.Cms.Api.Management/Controllers/Culture/AllCultureController.cs	Adds summary/description for listing available cultures (paged).

[AndyButland]

Thanks very much for kicking this off @OwainWilliams. I had a look over and made a few suggestions. Please see what you think - in some cases you may not agree and if so, please do say so or suggest further improvement. We can tweak further perhaps to set the pattens moving forward.

In the suggestions I've tried to standardise a little so we consistently use certain terms and punctuation, have simplified in some cases so we don't create an undue burden on ourselves going forward in describing every field or parameter, and avoided repeating something that's already in the Swagger UI. Finally, in a couple of cases I focussed more on the end result of the operation (so not just saying a flag is set for content clean up, but what this means in terms of the system behaviour).

[OwainWilliams]

Thanks @AndyButland - really appreciate the feedback. Sorry you had to do so much tidy up on it :) Hopefully it will give me and others a good guide though on what sort of language and info should be added to the summary and descriptions

[AndyButland]

You're welcome - looks good to me now and I think is a reasonable reference also for moving forward. @kjac - do you have any thoughts at this stage please, before @OwainWilliams or anyone else looks to create further endpoint descriptions?

[kjac]

I have thoughts.

I think it's awesome 🤩

[AndyButland]

Good to hear! So @OwainWilliams - please let us know what your plans are for these now. Although little and often is fine, it might make sense to do another round with a few more, and then we look to merge in and take others in future PRs. I think you should also retarget this PR to v17/dev, which will mean these would come at earliest in 17.1. Targeting main they'll be for 16.4, but I don't think they will make 17.0, so that's seems a little odd. And 17.1 gives a bit more time to be able to have a reasonable collection of endpoints documented. What do you think?

[OwainWilliams]

I'll see if I can get another couple of smaller sections done over the coming days. Don't want to lose momentum on this. Maybe target a few that are further up the list on the swagger page. Then I'd aim to keep that going, tick off more over the coming weeks. How does that sound?

[AndyButland]

Sounds perfect to me, thanks very much.