Why does Azure API Management OpenAPI 2.0 JSON Export of our API include a securityDefinitions object sometimes?

Question

We have an API defined in APIM that when we do an OpenAPI 2.0 export of the JSON it sometimes returns a securityDefinitions object that includes the subscription keys (example below):

    "securityDefinitions": {
        "apiKeyHeader": {
            "type": "apiKey",
            "name": "Ocp-Apim-Subscription-Key",
            "in": "header"
        },
        "apiKeyQuery": {
            "type": "apiKey",
            "name": "subscription-key",
            "in": "query"
        }
    },
    "security": [
        {
            "apiKeyHeader": []
        },
        {
            "apiKeyQuery": []
        }
    ]

This isn't consistent and we can't seem to find a rhyme or reason as to why APIM is including that in the export sometimes. The Subscription section of the API settings does not have the Subscription required box checked, nor does it seem toggling that field makes a difference for the export behavior.

What drives the inclusion of those sections in the exported API swagger?

Answer 1

Jeff Hellman

Welcome to Microsoft Q&A Platform!

Thank you for reaching out regarding the inconsistent inclusion of the securityDefinitions object in the OpenAPI 2.0 export from Azure API Management (APIM). I understand this can be confusing, and I am here to help you troubleshoot and resolve this issue.

The inclusion of the securityDefinitions object with subscription keys in the OpenAPI 2.0 export can be influenced by several factors.

1. Subscription Keys in Azure API Management: In APIM, subscription keys are commonly used to secure API access. Developers need to include a valid subscription key in HTTP requests when calling APIs published through APIM. Without a valid subscription key, the calls are rejected by the API Management gateway.
2. Export Behavior: The export behavior of the OpenAPI 2.0 JSON might be influenced by the configuration of the API in APIM. Even if the "Subscription required" box is not checked, there might be other settings or policies in place that trigger the inclusion of the securityDefinitions object.
3. API Management Subscriptions: Subscriptions in APIM are used to manage access to APIs. Each subscription is associated with a pair of subscription keys, and developers need to include these keys in their API requests. The export behavior might be related to how these subscriptions are configured and managed. You can find more information in the https://learn.microsoft.com/en-us/azure/api-management/api-management-subscriptions
4. Exporting API Details: When exporting API details, the format and content of the exported JSON can vary based on the API's configuration and the export settings. The inclusion of securityDefinitions might be a result of specific export parameters or settings. For more information, refer to the https://learn.microsoft.com/en-us/rest/api/apimanagement/api-export/get?view=rest-apimanagement-2024-05-01&tabs=HTTP
5. Restrictions and Details of API Formats Support: This article discusses the behavior of APIM during OpenAPI import and export, including limitations and requirements. You can review it here: https://learn.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions

To better understand and control this behavior, please review the API's configuration in APIM, including any policies or settings related to subscriptions and security. Additionally, checking the export settings and parameters might provide further insights into why the securityDefinitions object is sometimes included in the exported JSON.

By following these steps and reviewing the referenced documents, you should be able to identify and resolve the issue with the inconsistent inclusion of the securityDefinitions object in your OpenAPI 2.0 exports. If you need further assistance or have any questions, please feel free to reach out.