API 格式支持的限制和详细信息 - Azure API Management

OpenAPI/Swagger 导入限制

如果在导入 OpenAPI 文档时收到错误，请确保事先已通过以下方式之一对该文档进行验证：

使用 Azure 门户中的设计器（“设计”>“前端”>“OpenAPI 规范编辑器”）或

使用第三方工具（例如 Swagger 编辑器）。

URL 模板要求

所需路径和查询参数使用唯一名称 在 OpenAPI 中：

参数名称只需要在一个位置（例如路径、查询和头）内是唯一的。

在 API 管理中：

我们允许操作通过路径和查询参数进行区分。
由于 OpenAPI 不支持这种区分方式，因此我们要求参数名称在整个 URL 模板中是唯一的。

定义的 URL 参数 必须是 URL 模板的一部分。 可用的源文件 URL 应用于服务器相对 URL。无法引用外部文件。

OpenAPI 规范

支持的版本

API 管理仅支持：

OpenAPI 版本 2。

OpenAPI 版本 3.0.x（最高到版本 3.0.3）。

OpenAPI 版本 3.1（仅导入）

导入查询参数时，仅支持默认数组序列化方法（ style: form 、 explode: true ）。有关 OpenAPI 规范中的查询参数的更多详细信息，请参阅序列化规范。

不支持在 Cookie 中定义的参数。仍然可以使用策略来解码和验证 Cookie 的内容。

OpenAPI 版本 2

OpenAPI 版本 2 支持仅限于 JSON 格式。

不支持 “表单”类型参数。仍然可以使用策略来解码和验证 application/x-www-form-urlencoded 和 application/form-data 有效负载。

OpenAPI 版本 3.x

API 管理支持以下规范版本：

OpenAPI 3.0.3

OpenAPI 3.1.0 （仅导入）

HTTPS URL

如果指定了多个


    servers

，API 管理将使用它找到的第一个 HTTPS URL。

如果不存在任何 HTTPS URL，则服务器 URL 为空。


    example

以下字段包含在 OpenAPI 3.0.x 版或 OpenAPI 3.1.x 版中，但不受支持：

对于跨不同服务/环境的 API 定义的配置管理，请参阅有关将 API 管理服务与 Git 结合使用的文档。

通过 OpenAPI 导入添加新的 API

对于在 OpenAPI 文档中找到的每个操作，将创建一个新操作，其中：

将 Azure 资源名称设置为 operationId 。


    operationId

值已规范化。

如果未指定


    operationId

（不存在、为


    null

或为空），则会通过合并 HTTP 方法和路径模板来生成 Azure 资源名称值。

例如，


    get-foo

。

将会更改，以匹配 OpenAPI 文档中所述的 API。

通过将 OpenAPI 文档中操作的


    operationId

值与现有操作的 Azure 资源名称进行比较，以便与该文档中的操作匹配。

如果找到匹配项，则现有操作的属性将“就地”更新。

如果找不到匹配项：

通过合并 HTTP 方法和路径模板来创建新操作，例如 get-foo 。
对于每个新操作，导入过程会尝试从具有相同 HTTP 方法和路径模板的现有操作复制策略。
wsdl:import 、 xsd:import 和 xsd:include 指令不受支持。而是将依赖项合并到一个文档中。
如需用于解析和合并 WSDL 文件中的 wsdl:import 、 xsd:import 和 xsd:include 依赖项的开源工具，请参阅 GitHub 存储库。

WS-* 规范

不支持合并 WS-* 规范的 WSDL 文件。

包含多个部分的消息

不支持此消息类型。

WCF wsHttpBinding
使用 Windows Communication Foundation 创建的 SOAP 服务应使用 basicHttpBinding 。
不支持 wsHttpBinding 。
使用 MTOM 的服务可能会正常工作。
目前暂未提供官方支持。
API 管理不支持以递归方式定义的类型。
例如，引用这些类型本身的数组。

多个命名空间

虽然可以在架构中使用多个命名空间，但只能使用目标命名空间来定义消息部分。这些命名空间用于定义其他输入或输出元素。

在导出时不会保留除目标以外的命名空间。虽然你可以导入一个 WSDL 文档，用于定义具有其他命名空间的消息部分，但所有消息部分在导出时都会有 WSDL 目标命名空间。

SOAP 到 REST 转换仅支持包装的数组，如以下示例所示：

    <complexType name="arrayTypeName">
        <sequence>
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="typeName">
        <sequence>
            <element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
            <element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
            <element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
        </sequence>
    </complexType>
目前没有已知的 WADL 导入问题。