Add a Swagger documentation for the endpoints

[Timo Walter]

[Fabian Träger]

@tiwalter To add an example response for the endpoint GET platforms/{product}/{version} which returns the type PlatformsResponse in the swagger documentation just add a XML documentation to that returned type that contains the tag with example JSON data:

/// <summary>
/// Type that is returned reading the available platforms for a specific version of a product.
/// </summary>
/// <example>
/// {
/// 	"platforms":
///     [
///         "debian-amd64",
///         "debian-arm64"
///     ]
/// }
/// </example>
public class PlatformsResponseModel
{
    public List<string> Platforms { get; set; }
}

[Timo Walter]

@f-porter I considered your proposal with the example in the XML documentation, but the Swagger documentation didn't visualize this as a response example.

I used the Swashbuckle functionality that enables the example creation with using the IExamplesProvider interface

public class PlatformsResponseExample : IExamplesProvider<PlatformsResponseModel>
{
    public PlatformsResponseModel GetExamples()
    {
        return new PlatformsResponseModel
        {
            Platforms =  new List<string>()
            {
                "debian-amd64",
                "debian-arm64"
            }
        };
    }
}

This worked for me ;)

[Timo Walter]

Actually the Swagger documentation visualizes the "lock" icon for endpoints / actions that are not secured (marked with the "AllowAnonymous" attribute"). Also the authorization header will be send, if you fire requests against these endpoints with Swagger.

I investigated, how to disable the auth for these endpoints, but i didn't find a solution for this. I don't want to waste to much time on this behaviour. Actually it does not affect the functionality of the application.

I opened an issue on the Swashbuckle repo with this behaviour domaindrivendev/Swashbuckle.AspNetCore#1586. After i clarified how to disable auth for these endpoints, i will fix it ASAP. Maybe it's a bug of Swashbuckle and can be fixed with an update.

[Timo Walter]

Update:

The issue, mentioned above, is now fixed with the last commit.
I implemented a BasicAuthOperationsFilter that considers the "AllowAnonymous" attributes.

[Timo Walter]

Now, everything works as specified!