Get Even More Visitors To Your Blog, Upgrade To A Business Listing >>

Important changes to OpenAPI import and export

We introduced some changes in how Openapi import and export works in API Management. We made these changes based on customer feedback and to better align with OpenAPI semantics. The new behavior is in effect in the March 28 release when using Azure portal (including integrated Swagger editor) or management API version 2018-01-01 (or later).

Add new API via OpenAPI import

For each Operation found in the OpenAPI document, a new operation will be created with Azure resource name and display name set to operationId and summary respectively. operationId value is normalized following the rules described below. summary value is imported as-is and its length is limited to 300 characters.

If operationId is not specified, Azure resource name value will be generated by combining HTTP method and path template, e.g. get-foo.

If summary is not specified, display name value will be generated by combining HTTP method and path template, e.g. Get - /foo..

Update an existing API via OpenAPI import

During import existing API is changed to match API described in the OpenAPI document. Each operation in the OpenAPI document is matched to existing operation by comparing its operationId value to Azure resource name of existing operation.

If a match is found, existing operation's properties will be updated "in-place".

If a match is not found a new operation will be created using the rules described in the section above. For each new operation, the import will attempt to copy policies from an existing operation with the same HTTP method and path template.

All existing unmatched operations will be deleted.

To make import more predictable please follow these guidelines:

  • Make sure to specify operationId property for every operation.
  • Refrain from changing operationId after initial import.
  • Never change operationId and HTTP method or path template at the same time.

Export API as OpenAPI

For each operation, its Azure resource name will be exported as an operationId, and display name will be exported as a summary.

Normalization rules for operationId

  • Convert to lower case.
  • Replace each sequence of non-alphanumeric characters with a single dash, e.g. GET-/foo/{bar}?buzz={quix} will be transformed into get-foo-bar-buzz-quix-.
  • Trim dashes on both sides, e.g. get-foo-bar-buzz-quix- will become get-foo-bar-buzz-quix
  • Truncate to fit 76 characters, four characters less than maximum limit for a resource name.
  • Use remaining four characters for a deduplication suffix, if necessary, in the form of -1, -2, ..., -999.

Share the post

Important changes to OpenAPI import and export

×

Subscribe to Msdn Blogs | Get The Latest Information, Insights, Announcements, And News From Microsoft Experts And Developers In The Msdn Blogs.

Get updates delivered right to your inbox!

Thank you for your subscription

×