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).
GitHub-flavored Markdown (GFM) is not yet fully* supported in the description field.
* The Swagger specification itself supports GFM in the description field of several object types, as does OPS. However, AutoRest currently passes through GFM formatting tags directly, so **my bolded text** (including 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 for operation responses.
Format it as valid JSON (i.e. don't stuff it all into a string with \ns) and it'll be rendered as the raw JSON response object on docs. For an example, see the Monitor REST API reference
- Rendered: Monitor > AlertRules_Get (see Returns section)
- Source: insightsManagementClient_AlertRules.json line 184
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: