导入开放 API 规范时，Azure API 管理不遵守 operationId

Question

我从 Swashbuckle 生成了 swagger.json。将 open API 规范导入 Azure API 管理时，它不会使用 operationId 作为操作的名称。相反，它使用描述。我附上了产生问题的 JSON 样本。

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "Route Manager API"
  },
  "paths": {
    "/api/account/Logout": {
      "post": {
        "tags": [ "Account" ],
        "summary": "Logs the current user out of the system.",
        "operationId": "ApiAccountLogoutPost",
        "consumes": [],
        "produces": [],
        "parameters": [],
        "responses": { "200": { "description": "Logout successfully performed" } }
      }
    }
  }
}

以下示例在导入 Open API 规范时取自 Microsoft 文档，似乎使用 OperationId 作为名称 (GetSessions) 确实显示为 API 管理中函数的标题.

  "paths": {
    "/sessions": {
      "get": {
        "description": "A list of sessions.  Optional parameters work as filters to reduce the listed sessions.",
        "operationId": "GetSessions",
        "parameters": [
          {
            "name": "speakername",
            "in": "query",
            "type": "string"
          },
          {
            "name": "dayno",
            "in": "query",
            "description": "Format - int32.",
            "type": "integer"
          },
          {
            "name": "keyword",
            "in": "query",
            "type": "string"
          }
        ],
        "responses": { "200": { "description": "OK" } },
        "produces": [ "application/vnd.collection+json" ]
      }
    }

Answer 1

APIM 确实尊重 operationId，它的值用于将操作 ID 形成为 Azure 资源。您在 UI 上看到的是操作标题。使用 operationId 作为标题是错误的，因为 Open API 规范说：

Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.

人们不希望遵循带有操作标题的通用编程命名约定。因此 "summary" 字段被用作操作标题。

此处有更多详细信息：https://blogs.msdn.microsoft.com/apimanagement/2018/04/11/important-changes-to-openapi-import-and-export/

导入开放 API 规范时，Azure API 管理不遵守 operationId

Azure API Management not honoring the operationId when importing open API spec

azure-api-management