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.
|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
|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
Presentation (docs.microsoft.com UX)
|FEATURE 951476||Examples created with either the examples field or the
|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.|
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.
|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.|
The following items have been resolved following Q4 prioritization and are now available in production.
|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).|