How to validate OpenApi json spec and avoid errors on importing stage?

Question

Hi

Hoping You are doing well.

I have simple question. In the documentation (https://learn.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions) it is mentioned that Azure has more strict requirements and some limitations for Open API Documents.

What is the proper way to validate OpenAPI JSON before importing to Azure APIM to avoid any issues?
I can reproduce situation when validations through Swagger Editor or openapi-spec-validator do not show any errors. But when I am importing the same JSON into Azure APIM I get an error like "One or more fields contain incorrect values:".
I need to automate JSON validation somehow, what can You suggest for automation of validation?
Thank You

Answer 1

@sergei lozenkov Thanks for reaching out. When importing an OpenAPI document into Azure APIM, it's essential to validate the JSON beforehand to avoid issues during the import process. Using either Swagger Editor or openapi-spec-validator is a reliable way to catch any issues before importing into APIM. However, note that API import limitations exist, and some features may not be supported. Please refer to the official documentation for details on these restrictions and ensure that your OpenAPI document adheres to these limitations to avoid import failures.

https://learn.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions

Unfortunately, there is no automation process available for validating OpenAPI documents before importing them into APIM. If the OpenAPI Specification Validator does not show any errors or warnings, but you are still getting an error when importing the document into Azure APIM, it's possible that there is an issue with the Azure APIM service. In this case, you may need to contact Azure support for further assistance.

I hope this helps. Let me know if you have any other questions.

Answer 2

For all with the same problem ... if you try to import the API via PowerShell, you get a better statement about the failure reason at the output. That saved us a lot of effort

Like this:

$ApiMgmtContext = New-AzApiManagementContext -ResourceGroupName "<your rg>" -ServiceName "<your apim name>" 
Import-AzApiManagementApi -Context $ApiMgmtContext -SpecificationFormat "OpenApiJson" -SpecificationPath "your api def filepath" -Path "<whatever you name it>"