Служба управления API Azure не соблюдает идентификатор операции при импорте спецификации открытого API

У меня есть swagger.json, созданный из Swashbuckle. При импорте спецификации открытого API в систему управления API Azure он не использует 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" } }
      }
    }
  }
}

введите здесь описание изображения

Следующий пример взят из документации Microsoft при импорте спецификации Open API и, похоже, использует 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" ]
      }
    }

введите здесь описание изображения


person Geekn    schedule 28.08.2018    source источник


Ответы (1)


APIM соблюдает operationId, это значение используется для формирования идентификатора операции в качестве ресурса Azure. То, что вы видите в пользовательском интерфейсе, - это название операции. Неправильно использовать operationId в качестве заголовка, потому что спецификация Open API гласит:

Уникальная строка, используемая для идентификации операции. Идентификатор ДОЛЖЕН быть уникальным среди всех операций, описанных в API. Инструменты и библиотеки МОГУТ использовать OperationId для однозначной идентификации операции, поэтому рекомендуется следовать общепринятым соглашениям об именах программирования.

Не хотелось бы следовать общепринятым соглашениям об именах программирования с названием операции. Таким образом, вместо названия операции используется поле «Сводка».

Подробнее здесь: https://blogs.msdn.microsoft.com/apimanagement/2018/04/11/important-changes-to-openapi-import-and-export/

person Vitaliy Kurokhtin    schedule 30.08.2018
comment
О, хорошо ... Теперь я это вижу. Мой JSON предоставляет сводный узел, который используется поверх OpeationId. Спасибо. - person Geekn; 31.08.2018