Less style guide and more "cheat sheet," the following sections describe which fields or content are currently supported by docs.microsoft.com, the toolchain, and the Swagger/OpenAPI specification.
This document will be updated as features and support are added to the toolchain and docs.microsoft.com. As more features and support are added, this will become more of a style guide.
Not all Swagger documentation fields (summary, description, title) are supported by all Swagger object types. This is an OpenAPI specification restriction, not a docs.ms.com or toolchain restriction. The following table specifies which fields can be used for which object types in a Swagger *.json.
| Object type | summary | description | title |
|---|---|---|---|
| operation | X | X | |
| parameter | X | ||
| schema object | X | X |
summaryandtitlefields are appropriate for short-form documentation of 120 characters or less.descriptionis for long-form content, and can contain examples of use ("examples" in this context should not to be confused with the examples field).titleis not currently displayed on docs.microsoft.com.
GitHub-flavored Markdown (GFM) is not yet supported in the description field.
The Swagger specification itself supports GFM in the description field of several object types. However, AutoRest currently passes through GFM formatting tags directly, so **my bolded text** (with the asterisks) will end up in your generated clients' docs. Don't use GFM in Swagger spec descriptions yet.
Do not put HTML tags in any of the documentation fields.
You should populate the examples field, but it is not yet rendered on docs.microsoft.com.
Not all fields support overwrites. For example, only the summary and description fields of a Swagger spec can be overwritten in REST API documentation. See the DocFx documentation for lists of which fields can be overwritten: