Swagger spec cheat sheet

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.

Object type summary description title
operation X X
parameter X
schema object X X
  • summary and title fields are appropriate for short-form documentation of 120 characters or less.
  • description is 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.

HTML

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.

x-ms-examples

The x-ms-examples extension should be used for both request and response examples.

x-ms-examples usage

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

Overwrites

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:

Swagger validation

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.