Add guidance on operation summary & description

[tomkerkhove]

Add guidance on operation summary & description so that they are clear and human readable.

The guidance should indicate:

• What operation summary & description are
• What they are used for and how it related to API gateways
• What kind of information we are expecting
  • Business-oriented instead of technical docs
  • Human readable
• How they relate to operationId
• What Swagger is generated for the code sample

Our current guidance provides a good example:

/// <summary>
///     Get Health
/// </summary>
/// <remarks>Gets the current health status of the API</remarks>
[HttpGet]
[Route("health")]
[SwaggerOperation("Health_Get")]
[SwaggerResponse(HttpStatusCode.OK, "API is up & running")]
[SwaggerResponse(HttpStatusCode.InternalServerError, "API is not available")]
public IHttpActionResult Get()
{
    return Ok();
}

[MassimoC]

We moved away from [SwaggerOperation("Health_Get")] attribute with the swashbuckle 4.

[tomkerkhove]

This is not related to operationId but more the summary and description.

Can do this after holiday.

[tomkerkhove]

Thanks for picking this up @MassimoC !