[Maestro++/Darc] Maestro staging swagger broken

• This issue is blocking This blocks production deployments

• This issue is causing unreasonable pain

Going to https://maestro-int.westus2.cloudapp.azure.com/swagger/ui/index.html shows:

and has a link to https://validator.swagger.io/validator/debug?url=https%3A%2F%2Fmaestro-int.westus2.cloudapp.azure.com%2Fapi%2F2020-02-20%2Fswagger.json

which shows:

{
     "schemaValidationMessages": [
     {
        "level": "error",
        "message": "Can't read from file https://maestro-int.westus2.cloudapp.azure.com/api/2020-02-20/swagger.json"
    }]
}

This is likely related to the deletion of one of the 2020-02-20 controllers here: https://github.com/dotnet/arcade-services/pull/1745.

I attempted to run the https://github.com/dotnet/arcade-services/blob/722d732c4c202f7f92ed96355c7d5c59b719fbf3/src/Maestro/maestro-angular/src/maestro-client/generate-client.cmd script while pointing to the int website, and received an error:

HttpRequestException: Response status code does not indicate success: 500 (Internal Server Error). 
    at System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode() 
    at System.Net.Http.HttpClient.GetStreamAsyncCore(HttpRequestMessage request, CancellationToken cancellationToken) 
    at Microsoft.DotNet.SwaggerGenerator.MSBuild.GenerateSwaggerCode.GetSwaggerDocument(String input) in /_/src/Microsoft.DotNet.SwaggerGenerator/Microsoft.DotNet.SwaggerGenerator.MSBuild/GenerateSwaggerCode.cs:line 97 
    at Microsoft.DotNet.SwaggerGenerator.MSBuild.GenerateSwaggerCode.ExecuteAsync() in /_/src/Microsoft.DotNet.SwaggerGenerator/Microsoft.DotNet.SwaggerGenerator.MSBuild/GenerateSwaggerCode.cs:line 57
    at Microsoft.DotNet.SwaggerGenerator.MSBuild.GenerateSwaggerCode.Execute() in /_/src/Microsoft.DotNet.SwaggerGenerator/Microsoft.DotNet.SwaggerGenerator.MSBuild/GenerateSwaggerCode.cs:line 37

which seems related to the fact that we’re already getting the swagger errors.

[ChadNedzlek]

I believe we also fixed this already with a revert, so I’m going to move this to rollout?

[mmitche]

@dotnet/dnceng We need to get better about commenting.

There is often a lot of nuance in code, code that is written specifically to deal with special cases related to external factors (e.g. restrictions in services that we integrate with, specific data shapes), code that is written to deal with unexpected bug fixes, etc. We need to be better about commenting the why. We don’t always need to comment the what, but the why is important.

Even in code that is not particularly nuanced, we need to remember that it might be years between the team writing and reviewing it, and the next person coming along and changing it. Write comments as if no one will remember anything about why a piece of code was written, or what kind of design was chosen and for what reasons.

In the case related to this issue, a few comments in the class header or at the overrides, or even the base class would have made the why of the overrides clear. Otherwise there is no clear indication that the Channel types are different without deep inspection, and what effect this would have.