The following sections describe which fields or content are currently supported by docs.microsoft.com, the toolchain, and the Swagger/OpenAPI specification. Additionally, other notes and helpful hints related to Swagger spec authoring can be found here.
Documentation field support by object type
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.
titlefields 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)
The OpenAPI (Swagger) specification supports GitHub-flavored Markdown (GFM) in the
description field of the following object types:
You are highly encouraged to use GFM in
description fields for enhanced presentation of the documentation in your Swagger files. Your Markdown-formatted documentation will be rendered on docs.microsoft.com, and AutoRest will by default sanitize Markdown into plain text for code generators.
Do not put HTML tags in any of the documentation fields.
JSON request/response examples
You can provide both request and response examples using the
x-ms-examples extension, and response (only) examples with the built-in
examples field. An example of the required properties and parameters for every operation is required for a Swagger spec to pass the onboarding checklist.
The x-ms-examples extension should be used for both request and response examples.
- Rendered: Redis Cache Create operation on docs.microsoft.com
examples field and example object
You also can populate the
examples field of your response objects with Example Objects to present response JSON. 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
- Source: insightsManagementClient_AlertRules.json line 184
- Rendered: Monitor > AlertRules_Get (see Returns section)
Not all fields support overwrites. For example, only the
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:
The ADX repo has some good info on validating Swagger specs, as well as some information on their min-spec requirements for onboarding. See Azure Swagger Validation Tools.