Support for "see also" URL in documentation

[brjohnstmsft]

It is often useful in SDK documentation to have a "see also" with a reference to other documentation. For example, consider this generated C# code:

/// <summary>
/// Creates or updates a Resource. <see href="http://tempuri.org" />
/// </summary>

It would be great if we could put the URL in the Swagger spec consumed by AutoRest so that it could generate this kind of cross-reference in the documentation.

We should consider using externalDocs in swagger to represent this extra metadata.

https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#externalDocumentationObject

[brjohnstmsft]

Did some digging in the Swagger spec, and externalDocs isn't sufficient to cover all cases. For example, there is no mechanism to put any kind of documentation on enum labels. Perhaps we could create another x-ms extension for this.

[devigned]

I see where you are going with these documentation items. I'd rather see the documentation be sourced from the specification as much as possible. The external link is good, but why not just include the conceptual content as markdown?

[brjohnstmsft]

A lot of customers are already familiar with our REST API, and it helps them grok how the SDK works to see the correspondence between client operations and REST API operations. Plus, there's already a lot of great conceptual content on MSDN, and it would be a pain to duplicate it and maintain it in two places.

[devigned]

I agree it would be a pain to duplicate and maintain it in two places, that's precisely what I'm getting at. Right now, that documentation is in word docs and stuff. It would be awesome to encourage a more open authoring experience for reference documentation.

When I think of conceptual documentation, I think more about Azure.com rather than MSDN. I see MSDN being more of reference documentation.

[brjohnstmsft]

We use Markdown for both conceptual docs on Azure.com and reference docs on MSDN. The authoring experience for Azure.com is already open.

For reference docs, I'm not sure I see the value in trying to source REST API docs from the Swagger spec. It is a pretty poor vehicle for documentation (as my recently opened issues indicate). I see it more as a way to carry information that will be used to generate clients rather than a canonical representation of the API. It can't be; it's nowhere near complete. There will likely be large parts of the spec that are missing for Search because AutoRest won't be able to handle all the scenarios for our data plane API anyway.

Back to the issue at hand... I do think it's super useful to have links from client library reference docs back to corresponding REST API reference docs. Let's keep this discussion focused on that goal. I'd rather not have to ship a new version of our SDK with fewer docs than the current version; that is just not cool and I'm sure our customers would agree.

[brjohnstmsft]

FYI, I'm starting work on a PR for this issue.