Initial update to a couple of Management API endpoints

src/Umbraco.Cms.Api.Management/Controllers/Culture/AllCultureController.cs

@@ -28,6 +28,8 @@ public AllCultureController(IUmbracoMapper umbracoMapper, ICultureService cultur
     [HttpGet]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(PagedViewModel<CultureReponseModel>), StatusCodes.Status200OK)]
+    [EndpointSummary("Gets a paginated collection of cultures available for creating languages.")]
+    [EndpointDescription("Gets a paginated collection containing the English and localized names of all available cultures.")]
     public Task<PagedViewModel<CultureReponseModel>> GetAll(CancellationToken cancellationToken, int skip = 0, int take = 100)
     {
         CultureInfo[] all = _cultureService.GetValidCultureInfos();

src/Umbraco.Cms.Api.Management/Controllers/DataType/ByKeyDataTypeController.cs

@@ -1,4 +1,4 @@
-using Asp.Versioning;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.Cms.Api.Management.ViewModels.DataType;
@@ -24,6 +24,8 @@ public ByKeyDataTypeController(IDataTypeService dataTypeService, IUmbracoMapper
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(DataTypeResponseModel), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Get a data type by the provided Id.")]
+    [EndpointDescription("Get a data type by using the provided Id and the result returns the data types' properties.")]
     public async Task<IActionResult> ByKey(CancellationToken cancellationToken, Guid id)
     {
         IDataType? dataType = await _dataTypeService.GetAsync(id);

src/Umbraco.Cms.Api.Management/Controllers/DataType/ConfigurationDataTypeController.cs

@@ -1,4 +1,4 @@
-using Asp.Versioning;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Options;
@@ -18,6 +18,8 @@ public class ConfigurationDataTypeController : DataTypeControllerBase
     [HttpGet("configuration")]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(DatatypeConfigurationResponseModel), StatusCodes.Status200OK)]
+    [EndpointSummary("Gets the data type configuration.")]
+    [EndpointDescription("Gets the data type configuration settings.")]
     public Task<IActionResult> Configuration(CancellationToken cancellationToken)
     {
         var responseModel = new DatatypeConfigurationResponseModel

src/Umbraco.Cms.Api.Management/Controllers/DataType/CopyDataTypeController.cs

@@ -29,6 +29,8 @@ public CopyDataTypeController(IDataTypeService dataTypeService, IBackOfficeSecur
     [MapToApiVersion("1.0")]
     [ProducesResponseType(StatusCodes.Status201Created)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Copies a data type.")]
+    [EndpointDescription("Creates a duplicate of an existing data type identified by the provided unique Id. The copied data type will be given a new Id and have ' (copy)' appended to its name. Optionally, the copy can be placed in a specific container by providing a target container Id.")]
     public async Task<IActionResult> Copy(CancellationToken cancellationToken, Guid id, CopyDataTypeRequestModel copyDataTypeRequestModel)
     {
         IDataType? source = await _dataTypeService.GetAsync(id);

src/Umbraco.Cms.Api.Management/Controllers/DataType/CreateDataTypeController.cs

@@ -33,6 +33,8 @@ public CreateDataTypeController(IDataTypeService dataTypeService, IDataTypePrese
     [ProducesResponseType(StatusCodes.Status201Created)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Creates a new data type.")]
+    [EndpointDescription("Creates a new data type with the provided configuration.")]
     public async Task<IActionResult> Create(CancellationToken cancellationToken, CreateDataTypeRequestModel createDataTypeRequestModel)
     {
         var attempt = await _dataTypePresentationFactory.CreateAsync(createDataTypeRequestModel);

src/Umbraco.Cms.Api.Management/Controllers/DataType/DeleteDataTypeController.cs

@@ -29,6 +29,8 @@ public DeleteDataTypeController(IDataTypeService dataTypeService, IBackOfficeSec
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Deletes a data type.")]
+    [EndpointDescription("Deletes a data type identified by the provided Id.")]
     public async Task<IActionResult> Delete(CancellationToken cancellationToken, Guid id)
     {
         Attempt<IDataType?, DataTypeOperationStatus> result = await _dataTypeService.DeleteAsync(id, CurrentUserKey(_backOfficeSecurityAccessor));

src/Umbraco.Cms.Api.Management/Controllers/DataType/Filter/FilterDataTypeFilterController.cs

@@ -1,4 +1,4 @@
-using Asp.Versioning;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.Cms.Api.Common.ViewModels.Pagination;
@@ -26,6 +26,8 @@ public FilterDataTypeFilterController(IDataTypeService dataTypeService, IUmbraco
     [HttpGet]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(PagedViewModel<DataTypeItemResponseModel>), StatusCodes.Status200OK)]
+    [EndpointSummary("Gets a filtered collection of data types.")]
+    [EndpointDescription("Filters data types by name, editor UI alias, and editor alias with pagination support.")]
     public async Task<IActionResult> Filter(
         CancellationToken cancellationToken,
         int skip = 0,

src/Umbraco.Cms.Api.Management/Controllers/DataType/Folder/ByKeyDataTypeFolderController.cs

@@ -1,4 +1,4 @@
-using Asp.Versioning;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.Cms.Api.Management.ViewModels.Folder;
@@ -21,5 +21,7 @@ public ByKeyDataTypeFolderController(
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(FolderResponseModel), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Gets a data type folder.")]
+    [EndpointDescription("Gets a data type folder by identified by the provided Id. The result returns the folder's properties.")]
     public async Task<IActionResult> ByKey(CancellationToken cancellationToken, Guid id) => await GetFolderAsync(id);
 }

src/Umbraco.Cms.Api.Management/Controllers/DataType/Folder/CreateDataTypeFolderController.cs

@@ -1,4 +1,4 @@
-using Asp.Versioning;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.Cms.Api.Management.ViewModels.Folder;
@@ -22,6 +22,8 @@ public CreateDataTypeFolderController(
     [ProducesResponseType(StatusCodes.Status201Created)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Creates a data type folder.")]
+    [EndpointDescription("Creates a data type folder with the details provided in the request model.")]
     public async Task<IActionResult> Create(CancellationToken cancellationToken, CreateFolderRequestModel createFolderRequestModel)
         => await CreateFolderAsync<ByKeyDataTypeFolderController>(
             createFolderRequestModel,

src/Umbraco.Cms.Api.Management/Controllers/DataType/Folder/DeleteDataTypeFolderController.cs

@@ -1,4 +1,4 @@
-using Asp.Versioning;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.Cms.Core.Security;
@@ -21,5 +21,7 @@ public DeleteDataTypeFolderController(
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Deletes a data type folder.")]
+    [EndpointDescription("Deletes a data type folder identified by the provided Id.")]
     public async Task<IActionResult> Delete(CancellationToken cancellationToken, Guid id) => await DeleteFolderAsync(id);
 }

src/Umbraco.Cms.Api.Management/Controllers/DataType/Folder/UpdateDataTypeFolderController.cs

@@ -1,4 +1,4 @@
-using Asp.Versioning;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.Cms.Api.Management.ViewModels.Folder;
@@ -22,6 +22,8 @@ public UpdateDataTypeFolderController(
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Updates a data type folder.")]
+    [EndpointDescription("Updates a data type folder identified by the provided Id with the details provided in the request model.")]
     public async Task<IActionResult> Update(
         CancellationToken cancellationToken,
         Guid id,

src/Umbraco.Cms.Api.Management/Controllers/DataType/IsUsedDataTypeController.cs

@@ -21,6 +21,8 @@ public IsUsedDataTypeController(IDataTypeUsageService dataTypeUsageService)
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(bool), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Check if a data type is used.")]
+    [EndpointDescription("Checks if the data type with the provided Id is used in any content, media, or members.")]
     public async Task<IActionResult> IsUsed(CancellationToken cancellationToken, Guid id)
     {
         Attempt<bool, DataTypeOperationStatus> result = await _dataTypeUsageService.HasSavedValuesAsync(id);

src/Umbraco.Cms.Api.Management/Controllers/DataType/Item/ItemDatatypeItemController.cs

@@ -1,4 +1,4 @@
-using Asp.Versioning;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.Cms.Api.Management.ViewModels.DataType.Item;
@@ -23,6 +23,8 @@ public ItemDatatypeItemController(IDataTypeService dataTypeService, IUmbracoMapp
     [HttpGet]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(IEnumerable<DataTypeItemResponseModel>), StatusCodes.Status200OK)]
+    [EndpointSummary("Gets a collection of data type items.")]
+    [EndpointDescription("Get a collection of data type items identified by the provided Ids. Each result contains the data types' properties.")]
     public async Task<IActionResult> Item(
         CancellationToken cancellationToken,
         [FromQuery(Name = "id")] HashSet<Guid> ids)

src/Umbraco.Cms.Api.Management/Controllers/DataType/Item/SearchDataTypeItemController.cs

@@ -1,4 +1,4 @@
-using Asp.Versioning;
+using Asp.Versioning;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.Cms.Api.Management.ViewModels.DataType.Item;
@@ -26,6 +26,8 @@ public SearchDataTypeItemController(IEntitySearchService entitySearchService, ID
     [HttpGet("search")]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(PagedModel<DataTypeItemResponseModel>), StatusCodes.Status200OK)]
+    [EndpointSummary("Search data types by query.")]
+    [EndpointDescription("Gets a paged collection of data type items identified by provided query.")]
     public async Task<IActionResult> Search(CancellationToken cancellationToken, string query, int skip = 0, int take = 100)
     {
         PagedModel<IEntitySlim> searchResult = _entitySearchService.Search(UmbracoObjectTypes.DataType, query, skip, take);

src/Umbraco.Cms.Api.Management/Controllers/DataType/MoveDataTypeController.cs

@@ -29,6 +29,8 @@ public MoveDataTypeController(IDataTypeService dataTypeService, IBackOfficeSecur
     [MapToApiVersion("1.0")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Moves a data type.")]
+    [EndpointDescription("Moves an existing data type identified by Id to a different container. The target container Id must be provided in the request model.")]
     public async Task<IActionResult> Move(CancellationToken cancellationToken, Guid id, MoveDataTypeRequestModel moveDataTypeRequestModel)
     {
         IDataType? source = await _dataTypeService.GetAsync(id);

src/Umbraco.Cms.Api.Management/Controllers/DataType/References/ReferencedByDataTypeController.cs

@@ -27,6 +27,8 @@ public ReferencedByDataTypeController(IDataTypeService dataTypeService, IRelatio
     [HttpGet("{id:guid}/referenced-by")]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(PagedViewModel<IReferenceResponseModel>), StatusCodes.Status200OK)]
+    [EndpointSummary("Gets a paged collection of entities that are referenced by a data type.")]
+    [EndpointDescription("Gets a paged collection of entities that are referenced by the data type with the provided Id, so you can see where it is being used.")]
     public async Task<ActionResult<PagedViewModel<IReferenceResponseModel>>> ReferencedBy(
         CancellationToken cancellationToken,
         Guid id,

src/Umbraco.Cms.Api.Management/Controllers/DataType/Tree/AncestorsDataTypeTreeController.cs

@@ -26,6 +26,8 @@ public AncestorsDataTypeTreeController(IEntityService entityService, FlagProvide
     [HttpGet("ancestors")]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(IEnumerable<DataTypeTreeItemResponseModel>), StatusCodes.Status200OK)]
+    [EndpointSummary("Gets a collection of ancestor data type folders.")]
+    [EndpointDescription("Gets a collection of data type folders that are ancestors to the provided Id. The result returns the ancestor folders' properties.")]
     public async Task<ActionResult<IEnumerable<DataTypeTreeItemResponseModel>>> Ancestors(CancellationToken cancellationToken, Guid descendantId)
         => await GetAncestors(descendantId);
 }

src/Umbraco.Cms.Api.Management/Controllers/DataType/Tree/ChildrenDataTypeTreeController.cs

@@ -27,6 +27,8 @@ public ChildrenDataTypeTreeController(IEntityService entityService, FlagProvider
     [HttpGet("children")]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(PagedViewModel<DataTypeTreeItemResponseModel>), StatusCodes.Status200OK)]
+    [EndpointSummary("Gets a collection of data type tree child items.")]
+    [EndpointDescription("Gets a paged collection of data type tree items that are children of the provided parent Id. The collection can be optionally filtered to return only folder, or folders and data types.  The result returns the data type tree items' properties.")]
     public async Task<ActionResult<PagedViewModel<DataTypeTreeItemResponseModel>>> Children(CancellationToken cancellationToken, Guid parentId, int skip = 0, int take = 100, bool foldersOnly = false)
     {
         RenderFoldersOnly(foldersOnly);

src/Umbraco.Cms.Api.Management/Controllers/DataType/Tree/RootDataTypeTreeController.cs

@@ -27,6 +27,8 @@ public RootDataTypeTreeController(IEntityService entityService, FlagProviderColl
     [HttpGet("root")]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(typeof(PagedViewModel<DataTypeTreeItemResponseModel>), StatusCodes.Status200OK)]
+    [EndpointSummary("Gets a collection of data type items from the root of the data type tree.")]
+    [EndpointDescription("Gets a paged collection of data type items from the root of the data type tree. The collection can be optionally filtered to return only folder, or folders and data types. The result returns the data type tree items' properties.")]
     public async Task<ActionResult<PagedViewModel<DataTypeTreeItemResponseModel>>> Root(CancellationToken cancellationToken, int skip = 0, int take = 100, bool foldersOnly = false)
     {
         RenderFoldersOnly(foldersOnly);

src/Umbraco.Cms.Api.Management/Controllers/DataType/Tree/SiblingsDataTypeTreeController.cs

@@ -24,6 +24,8 @@ public SiblingsDataTypeTreeController(IEntityService entityService, FlagProvider
 
     [HttpGet("siblings")]
     [ProducesResponseType(typeof(SubsetViewModel<DataTypeTreeItemResponseModel>), StatusCodes.Status200OK)]
+    [EndpointSummary("Gets a collection of data type tree sibling items.")]
+    [EndpointDescription("Gets a paged collection of data type tree items that are siblings of the provided parent Id. The collection can be optionally filtered to return only folder, or folders and data types.  The result returns the data type tree items' properties.")]
     public async Task<ActionResult<SubsetViewModel<DataTypeTreeItemResponseModel>>> Siblings(CancellationToken cancellationToken, Guid target, int before, int after, bool foldersOnly = false)
     {
         RenderFoldersOnly(foldersOnly);

src/Umbraco.Cms.Api.Management/Controllers/DataType/UpdateDataTypeController.cs

@@ -33,6 +33,8 @@ public UpdateDataTypeController(IDataTypeService dataTypeService, IBackOfficeSec
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [EndpointSummary("Updates a data type.")]
+    [EndpointDescription("Updates a data type by identified by the provided Id with the details provided in the request model.")]
     public async Task<IActionResult> Update(CancellationToken cancellationToken, Guid id, UpdateDataTypeRequestModel updateDataTypeViewModel)
     {
         IDataType? current = await _dataTypeService.GetAsync(id);

src/Umbraco.Cms.Api.Management/Controllers/DocumentVersion/AllDocumentVersionController.cs

@@ -31,6 +31,8 @@ public AllDocumentVersionController(
     [ProducesResponseType(typeof(PagedViewModel<DocumentVersionItemResponseModel>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [EndpointSummary("Gets a paginated collection of versions for a specific document.")]
+    [EndpointDescription("Gets a paginated collection of versions for a specific document and optional culture. Each result describes the version and includes details of the document type, editor, version date, and published status.")]
     public async Task<IActionResult> All(
         CancellationToken cancellationToken,
         [Required] Guid documentId,

src/Umbraco.Cms.Api.Management/Controllers/DocumentVersion/ByKeyDocumentVersionController.cs

@@ -29,6 +29,8 @@ public ByKeyDocumentVersionController(
     [ProducesResponseType(typeof(DocumentVersionResponseModel), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [EndpointSummary("Gets a specific document version.")]
+    [EndpointDescription("Gets a specific document version by its Id. If found, the result describes the version and includes details of the document type, editor, version date, and published status.")]
     public async Task<IActionResult> ByKey(CancellationToken cancellationToken, Guid id)
     {
         Attempt<IContent?, ContentVersionOperationStatus> attempt =

src/Umbraco.Cms.Api.Management/Controllers/DocumentVersion/RollbackDocumentVersionController.cs

@@ -36,6 +36,8 @@ public RollbackDocumentVersionController(
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [EndpointSummary("Rolls back a document to a specific version.")]
+    [EndpointDescription("Rolls back a document to the version indicated by the provided Id. This will archive the current version of the document and publish the provided one.")]
     public async Task<IActionResult> Rollback(CancellationToken cancellationToken, Guid id, string? culture)
     {
         Attempt<IContent?, ContentVersionOperationStatus> getContentAttempt =

src/Umbraco.Cms.Api.Management/Controllers/DocumentVersion/UpdatePreventCleanupDocumentVersionController.cs

@@ -27,6 +27,8 @@ public UpdatePreventCleanupDocumentVersionController(
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
+    [EndpointSummary("Sets the prevent clean up status for a document version.")]
+    [EndpointDescription("Sets the prevent clean up boolean status for a document version to the provided value. This controls whether the version will be a candidate for removal in content history clean up.")]
     public async Task<IActionResult> Set(CancellationToken cancellationToken, Guid id, bool preventCleanup)
     {
         Attempt<ContentVersionOperationStatus> attempt =