Documentation for operation groups

[brjohnstmsft]

Currently there is no place in Swagger specs to add documentation for enum labels or operation groups. The end result is missing documentation in the generated code. For example, the operation group property ISearchManagementClient.Services used to have a comment and URL that referred to the corresponding section of the REST API docs on MSDN, but there is no home for this documentation in the Swagger spec.

Our users deserve awesome docs. We should consider a Swagger extension for adding documentation for operation groups and enum labels (also URL references; see related issue: #288).

[devigned]

Hmm... why not have the documentation contain the markdown content that would be displayed in MSDN?

[brjohnstmsft]

But where would it go? You can't attach documentation to enum labels or operation groups anymore. For example, here is how the C# code for a simple enum used to look before AutoRest:

/// <summary> 
/// Defines the SKU of an Azure Search Service, which determines price tier 
/// and capacity limits. 
/// </summary> 
public enum SkuType 
{ 
    /// <summary> 
    /// Indicates a free Search service. 
    /// </summary> 
    Free = 0, 

    /// <summary> 
    /// Indicates a standard Search service with dedicated resources. 
    /// </summary> 
    Standard = 1, 

    /// <summary> 
    /// Indicates a dedicated search service with additional capacity for 
    /// higher throughput and storage. Use only under the guidance of 
    /// Microsoft support.  (see 
    /// http://azure.microsoft.com/pricing/details/search/ for more 
    /// information) 
    /// </summary> 
    Standard2 = 2, 
} 

Here is how it looks with AutoRest:

/// <summary>
/// Defines values for SkuType.
/// </summary>
[JsonConverter(typeof(StringEnumConverter))]
public enum SkuType
{
    [EnumMember(Value = "free")]
    Free,
    [EnumMember(Value = "standard")]
    Standard,
    [EnumMember(Value = "standard2")]
    Standard2
}

The missing /// comments mean missing documentation when it gets published to MSDN, and also missing Intellisense tooltips in Visual Studio. The docs are missing because they're not in the Swagger spec (because there's nowhere in the Swagger spec to put them).

[brjohnstmsft]

Here's the relevant Swagger discussion for documenting enum labels: OAI/OpenAPI-Specification#348

[henkosch]

+1

[matthchr]

+1 to this

[olydis]

Documentation for enum values is a thing now as such:

x-ms-enum:
  name: <name for generated type>
  modelAsString: true|false
  values:  <array of one or more enum-values:>
    - value: <wire-value>
      description: <description of that value>
      name: <generated enum member name (defaults to ‘value’)>

It was implemented by #2308

I've changed the title of this issue accordingly.

[fearthecowboy]

Adding operation group docs to vNext design