Open API Specification 3 (OAS3) has been around for a while now, and the Azure API Management team has worked on its OAS3 implementation for a good 1,5 years. But now, finally, the OAS3 support is generally available. OpenAPI Specification v3 is the latest major version of the well-known open-source interface specification for REST APIs. Azure API Management’s implementation is using the OpenAPI.NET SDK project. Azure API Management has interoperability between OpenAPI versions so that, for example, schema definitions are converted between OpenAPI v2 (swagger) and OpenAPI 3.

The OpenAPI v3 functionality is ready for production use in the latter half of February 2020.

What exactly is Open API Specification 3?

Open API Specification 3 (or just OAS3) is an interface specification used to describe a REST API. The “OpenAPI Initiative” governs the OAS3 standard. The “Open API Initiative” (OAI) is a consortium formed by industry experts. They produce OAS3 as an open structure, and the work is part of the Linux Foundation.

Before OAS3, we had OAS2. OAS2 is commonly referred to as “Swagger 2.0“, and this specification is actually not developed by OAI. Swagger 2.0 was initially developed by Tony Tam from the dictionary website Worknik and published using an open source license. All interests and rights for Swagger 2.0 were held by Wordnik’s parent company Reverb Technologies (later Inform, Inc.). Software tools giant, SmartBear, bought Swagger 2.0 out of Revert Technologies in 2015. Later that year, November 5th, 2015, Open API Initiative was formed by SmartBear,3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, and Restlet.

How to import an Open API Specification 3 into Azure API Management?

In Azure API Management lingo, the Open API Specification 3 is just referred to as “OpenAPI.”

Here is an example of how to import an Open API Specification 3 using the Azure PowerShell SDK:

PS C:\>$context = New-AzApiManagementContext -ResourceGroupName
“MY-APIPLATFORM-rg” -ServiceName
“MY-APIPLATFORM-apim”

PS C:\> Import-AzApiManagementApi -Context $context -SpecificationFormat
OpenApi -SpecificationUrl https://raw.githubusercontent.com/path/to/myapi30.json -Path
“myapi30”

Note that the parameter “-SpecificationFormat
OpenApi”
specidies that the format of the imported specification is Open API Specification 3.0.

If you use the Azure Resource Manager REST API things look are bit different:

Request:

• PUT https://management.azure.com/subscriptions/subid/resourceGroups/MY-APIPLATFORM-rg/providers/Microsoft.ApiManagement/service/ MY-APIPLATFORM-apim /apis/myapi30?api-version=2019-01-01
  
• Body:
  
  • {
      “properties”: {
        “format”: “openapi-link”,
        “value”: “https://raw.githubusercontent.com/path/to/myapi30.json“,
        “path”: “myapi30”
      }
    }

The property “format” in the request body can be one of the following OAS3 variants:

Response (202):

{
  “id”: “/subscriptions/subid/resourceGroups/MY-APIPLATFORM-rg/providers/Microsoft.ApiManagement/service/ MY-APIPLATFORM-apim /apis/myapi30“,
  “type”: “Microsoft.ApiManagement/service/apis”,
  “name”: “myapi30”,
  “properties”: {
    “displayName”: “My API OAS 3.0”,
    “apiRevision”: “1”,
    “serviceUrl”: “http://myapi30.io/v1”,
    “path”: “myapi30”,
    “protocols”: [
      “https”
    ],
    “subscriptionKeyParameterNames”: {
      “header”: “Ocp-Apim-Subscription-Key”,
      “query”: “subscription-key”
    },
    “isCurrent”: true
  }
}

Note: Reponse also comes as HTTP 200 (update), and HTTP 202 (async).