Migrating to Swagger-generated documentation

Recommendations and considerations for content developers and partners

The following addresses questions that might be posed by content or partner teams when considering the move to Swagger. Presented in Q&A format, it is intended to help teams make informed decisions about migrating from MSDN or hand-authored reference content to the autogenerated reference documentation experience on docs.microsoft.com.

Question: Should my team create a Swagger specification for our service?

Answer: Yes. All teams are encouraged to move forward with generating a Swagger specification to define the APIs in their service. Whether you choose to publish autogenerated documentation from your specification does not factor into the decision of whether to move forward with Swagger adoption.

Question: Should we use the API reference content generated by the Open Publishing System (OPS) and published to docs.microsoft.com for our service?

Answer: Yes, unless your team considers one or more of the following issues a blocker. Because each service is unique in both maturity and complexity, a single answer cannot apply to all. Here are some of the primary items to consider when making your decision.

Engineering Improvements to REST API Reference

The following issues are currently blocking one or more partners from onboarding to Swagger, migrating to Swagger-generated content on docs.microsoft.com, or both.

Infrastructure/tooling

Tracking Item Description
FEATURE 939898 Changes to a Swagger specification that has already been onboarded are published automatically to the live site. This can have the unintended consequence of publishing content changes (such as unannounced features) before the team is ready.
FEATURE 949928 Private staging and preview of an unreleased Swagger specification is currently unsupported. To stage and view the documentation generated from your Swagger specification, it must be placed in the public azure-rest-api-specs repository before being published to the staging site, review.docs.microsoft.com.
FEATURE 928260 Specifications that define a parameterized host field (such as with x-parameterized-host) currently do not display the correct URL in generated API reference content.
FEATURE 951073 A polymorphic model for schema object definitions is not currently processed and displayed correctly by OPS.
FEATURE 950578 OPS continually expands self-referencing schema objects, causing timeouts when generating documentation from the Swagger specification.
FEATURE 950589 OPS doesn’t process the x-ms-discriminator-value extension recommended by the AutoRest team to represent type hierarchy, causing a lack of descriptions for derived types.

Presentation (docs.microsoft.com UX)

Tracking Item Description
FEATURE 951476 Examples created with either the examples field or the x-ms-examples extension are not presented as raw request/response JSON, but instead are displayed as schema JSON including elements like responses and 201.
FEATURE 949745 Heavily-nested parameter layout, with every property for every schema object appearing on-page, creates difficult to navigate documentation and unwieldy page length.

Non-blocking Items

While not currently blocking partner onboarding, these items have been specified by partners as requirements for a positive customer experience, and in some cases, are required for "min-spec" or parity experience with MSDN.

Tracking Item Description
FEATURE 950603 Inter-topic linking—referencing an element in one API from another—is unsupported.
FEATURE 950650 Enum values cannot be described individually.
FEATURE 950658 No handling of tag field, thus no way to control/create custom TOC layout.
FEATURE 794917 Each page contains a full operation group instead of a single operation.
FEATURE 950607 Examples cannot be decorated with a description.
FEATURE 950599 Literate editing format (YAML) is not yet supported end-to-end. As such, a GFM-friendly editing experience is unavailable, preventing complex formatting (e.g. bulleted lists, friendly hyperlinks, bold, italics) from being included in Swagger specifications.

Resolved Items

The following items have been resolved following Q4 prioritization and are now available in production.

Tracking Item Description
FEATURE 928906 Schema object definitions in external files are currently unsupported by OPS. While valid in Swagger specifications, reference content for specifications that split their model schema among multiple files cannot currently be published.
FEATURE 950644 AutoRest doesn't transform GFM to readable content when generating managed client code. This causes raw GFM tags to appear in the generated clients’ documentation (C# XML docs, for example).