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

sergei lozenkov 5

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

Charlie Wei 1,900 Reputation points

2024-03-27T22:54:57.0166667+00:00
Hello sergei lozenkov,

You can refer to this document: Import an Azure OpenAI API as a REST API.

In the servers element in the specification, substitute the name of your Azure OpenAI resource endpoint for the placeholder values in the specification. The following example servers element is updated with the contoso.openai.azure.com resource endpoint.

[...] "servers": [ { "url": "https://contoso.openai.azure.com/openai", "variables": { "endpoint": { "default": "contoso.openai.azure.com" } } } ], [...]

Best regards,
Charlie

If you find my response helpful, please consider accepting this answer and voting yes to support the community. Thank you!
sergei lozenkov 5 Reputation points

2024-03-27T23:30:44.5166667+00:00

Thank You for the answer. But it is not that I asked.
Right now I have specific pipeline. One job - makes validation by executing "openapi-spec-validator api.json", and another job - imports api spec to the Azure APIM Management.
Unfortunately, I discovered that my validation step cannot prevent issues with import job due to more strict requirements from the Azure APIM side.

I need to improve validation process. Documentation cannot give anything in automation.
Does the Azure have some separate tool, like "openapi-spec-validator" that I can use to satisfy all requirements for JSON document?

Important thing.
I need to execute validation process before import job. And validation job should not change anything in the Azure APIM management.
sergei lozenkov 5 Reputation points

2024-03-28T11:00:11.1433333+00:00

I am wondering, if I the first person who asked this.
As I understood, Azure APIM Manager has some specific validation process when import operation is initiated. And can show some discrepancies if validation is failed.
Can I use the same validation before import operation?
My only purpose is to get proper OpenAPI JSON that wil not have any issues while importing.
Thank You

1 answer

JananiRamesh-MSFT 21,171 Reputation points

2024-03-29T05:31:43.7566667+00:00

@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.
Please sign in to rate this answer.
sergei lozenkov 5 Reputation points

2024-03-29T11:14:06.2533333+00:00

@JananiRamesh-MSFT Thank You for the answer.
Please could You tell something about this project https://github.com/Azure/autorest
As I understood there is ability to validate API spec by
autorest --azure-validator --v3 --input-file=badapi.json

Does it work?

JananiRamesh-MSFT 21,171 Reputation points

2024-04-02T07:23:41.6566667+00:00

@sergei lozenkov Thanks for getting back, I had never used it before, AutoRest is an open source tool that generates client libraries for accessing RESTful web services. It can also be used to validate the API specification using the --azure-validator flag. This flag is used to validate the API specification against the Azure API Guidelines.

do let me know incase of further queries, I would be happy to assist you.

Please accept as Yes if the above provided answer is useful, so that you can help others in the community looking for remediation for similar issues.

sergei lozenkov 5 Reputation points

2024-04-02T11:26:10.19+00:00

After some testing I discovered that unfortunately autorest is not stable solution. We cannot use it.
IMHO, absense of separate internal validator is lack of functionality from Azure.

JananiRamesh-MSFT 21,171 Reputation points

2024-04-02T12:00:35.35+00:00

@sergei lozenkov Thanks for getting back, I'm sorry to hear that you have experienced issues with AutoRest. please have a look at this GitHub - microsoft/OpenAPI.NET: The OpenAPI.NET SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OpenAPI JSON and YAML documents from the model.

sergei lozenkov 5 Reputation points

2024-04-02T12:37:11.3966667+00:00

@JananiRamesh-MSFT Yes. I've already seen this project. Unfortunately, I do not see any useful docs here. I mean the actual validation process with help of this library.
Sign in to comment