Output notification handler messages as a header

[kjac]

Prerequisites

• I have added steps to test this contribution in the description below

Description

This PR appends notification messages from serverside notification handlers to the Management API output. The notification messages are output in the Umb-Notifications header. The Swagger docs should reflect this.

Messages are only ever appended to non-GET API operations, as notifications are only produced on state changes. Likewise, 401 responses will never produce notifications, so these have been explicitly filtered out when appending the Umb-Notifications header in the OpenAPI schema.

Testing this PR

1. Create one or more notification handlers that append messages to the notifications.
2. Perform operations that invoke these handlers.
3. Verify that the notification messages are returned in the Umb-Notifications header.
4. Verify that GET operations are not subject to the Umb-Notifications header - neither in API outputs, nor in the Swagger docs.
5. Verify that 401 operations do not list the Umb-Notifications header in the Swagger docs.

A code snippet for testing has been included below.

Test notification handlers

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace Umbraco.Cms.Web.UI.New.Custom;

public class MyNotificationHandlerComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder
            .AddNotificationHandler<DataTypeSavingNotification, MyFirstNotificationHandler>()
            .AddNotificationHandler<DataTypeSavingNotification, MySecondNotificationHandler>();

    private class MyFirstNotificationHandler : INotificationHandler<DataTypeSavingNotification>
    {
        public void Handle(DataTypeSavingNotification notification)
            => notification.Messages.Add(new EventMessage("First Category", "Hello from the First Notification Handler", EventMessageType.Info));
    }

    private class MySecondNotificationHandler : INotificationHandler<DataTypeSavingNotification>
    {
        public void Handle(DataTypeSavingNotification notification)
            => notification.CancelOperation(new EventMessage("Second Category", "Hello from the Second Notification Handler", EventMessageType.Success));
    }
}