Documentation for operation groups

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: https://github.com/Azure/autorest/issues/288).

[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