Ошибка No operations defined in spec в MMLibSwagger

Ошибка «No operations defined in spec!» в MMLib.SwaggerForOcelot обычно возникает, когда библиотека не удаётся корректно преобразовать спецификации Swagger downstream‑сервисов в объединённый Swagger Ocelot из‑за несоответствий в конфигурации или проблем с обработкой шаблонов путей. На основе вашего окружения проблема, скорее всего, связана с тем, как библиотека обрабатывает переменные шаблонов пути во время трансформации.

Содержание

• Понимание причины
• Исправления конфигурации
• Продвинутая отладка
• Альтернативные решения
• Лучшие практики

Понимание причины

Основная проблема в том, что MMLib.SwaggerForOcelot удаляет все пути из swagger.json downstream‑сервиса во время процесса трансформации Ocelot. Это происходит, потому что библиотека пытается сопоставить пути downstream‑сервиса с конфигурацией маршрутов Ocelot, но не умеет корректно обрабатывать переменные шаблонов.

Согласно GitHub issue #19, «это происходит из‑за двойных {} переменных в PathTemplate». В вашей конфигурации DownstreamPathTemplate использует /api/{url}, тогда как фактический путь downstream‑сервиса — /api/weather-forecast. Библиотека не может корректно сопоставить эти шаблоны.

Другой ключевой момент, подтверждённый исследованием на Stack Overflow, — «MMLib.SwaggerForOcelot не учитывает {version} при трансформации Ocelot», что указывает на более широкие проблемы с обработкой переменных шаблонов.

Исправления конфигурации

1. Настройка сопоставления шаблонов пути

Самое распространённое решение — убедиться, что шаблоны путей совпадают точно между маршрутом Ocelot и путями Swagger downstream‑сервиса:

{
  "Routes": [
    {
      "UpstreamPathTemplate": "/api/test/{url}",
      "DownstreamPathTemplate": "/api/{url}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "test-host",
          "Port": 8080
        }
      ],
      "SwaggerKey": "test",
      "UpstreamHttpMethod": ["GET", "POST", "PUT", "DELETE"]
    }
  ],
  "SwaggerEndPoints": [
    {
      "Key": "test",
      "Config": [
        {
          "Name": "Test API",
          "Version": "v1",
          "Url": "http://test-host:8080/swagger/v1/swagger.json"
        }
      ]
    }
  ]
}

2. Настройка свойства TransformByOcelotConfig

Добавьте свойство TransformByOcelotConfig в конфигурацию SwaggerEndpoints. Как отмечено в обсуждениях Stack Overflow, вы можете установить его в false, чтобы обойти трансформацию:

{
  "SwaggerEndPoints": [
    {
      "Key": "test",
      "TransformByOcelotConfig": false,
      "Config": [
        {
          "Name": "Test API",
          "Version": "v1",
          "Url": "http://test-host:8080/swagger/v1/swagger.json"
        }
      ]
    }
  ]
}

Однако, как вы отметили, это покажет эндпоинты с внутренними/ downstream‑путями вместо upstream‑путей. Для правильного решения оставьте true, но убедитесь, что шаблоны путей совпадают корректно.

3. Исправление конфигурации маршрута

Убедитесь, что ваша конфигурация маршрута полная и включает все необходимые свойства. Согласно GitHub issue #90, правильная конфигурация должна выглядеть так:

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "test-host",
          "Port": 8080
        }
      ],
      "UpstreamPathTemplate": "/api/test/{everything}",
      "UpstreamHttpMethod": ["GET", "POST", "PUT", "DELETE"],
      "SwaggerKey": "test"
    }
  ],
  "SwaggerEndPoints": [
    {
      "Key": "test",
      "Config": [
        {
          "Name": "Test API",
          "Version": "v1",
          "Url": "http://test-host:8080/swagger/v1/swagger.json"
        }
      ]
    }
  ]
}

Продвинутая отладка

1. Проверка совместимости версий пакетов

Версии ваших пакетов выглядят совместимыми, но несовпадения версий могут вызывать проблемы. Согласно NuGet Gallery, убедитесь, что вы используете совместимые версии:

• Microsoft.AspNetCore.OpenApi 9.0.11
• MMLib.SwaggerForOcelot 9.0.0
• Swashbuckle.AspNetCore 9.0.6

Попробуйте протестировать с разными версиями, чтобы исключить проблемы совместимости.

2. Проверка переменных шаблонов пути

Проблема часто возникает из‑за того, как обрабатываются переменные шаблонов. Убедитесь, что имена переменных согласованы:

{
  "Routes": [
    {
      "UpstreamPathTemplate": "/api/test/{everything}",
      "DownstreamPathTemplate": "/api/{everything}"
      // ...
    }
  ]
}

Использование {everything} вместо {url} может помочь решить проблемы с сопоставлением шаблонов, как отмечено в нескольких обсуждениях GitHub.

3. Отладка процесса трансформации

Добавьте логирование, чтобы понять, что происходит во время трансформации. Вы можете проверить, какая спецификация Swagger загружается до и после трансформации:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Это поможет увидеть, загружается ли downstream‑swagger корректно, но затем удаляется во время трансформации.

Альтернативные решения

1. Использование прямого шаблона пути downstream

Если вы обслуживаете только один API, рассмотрите возможность использования более прямого шаблона пути:

{
  "Routes": [
    {
      "UpstreamPathTemplate": "/api/test/weather-forecast",
      "DownstreamPathTemplate": "/api/weather-forecast"
      // ...
    }
  ]
}

Это устраняет проблемы с сопоставлением переменных шаблонов.

2. Реализация пользовательской трансформации Swagger

Для сложных сценариев может потребоваться реализовать пользовательскую логику трансформации. Согласно обсуждениям GitHub, вы можете программно настроить Swagger‑эндпоинты:

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerForOcelot(Configuration);
    services.AddOcelot();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseOcelot().Wait();
    app.UseSwaggerForOcelotUI(opt =>
    {
        opt.PathToSwaggerGenerator = "/swagger/docs";
        opt.DownstreamSwaggerEndPointBasePath = "/api/v1/swagger/docs";
    });
}

3. Использование нескольких Swagger‑ключей

Если у вас несколько сервисов, используйте отдельные Swagger‑ключи для каждого сервиса, как показано в примерной конфигурации:

{
  "SwaggerEndPoints": [
    {
      "Key": "bffweb",
      "TransformByOcelotConfig": false,
      "Config": [
        {
          "Name": "BFF.Web",
          "Version": "1.0",
          "Url": "http://localhost:5205/swagger/v1/swagger.json"
        }
      ]
    },
    {
      "Key": "location",
      "TransformByOcelotConfig": true,
      "Config": [
        {
          "Name": "Location.API",
          "Version": "1.0",
          "Url": "http://localhost:5205/location/swagger/v1/swagger.json"
        }
      ]
    }
  ]
}

Лучшие практики

1. Проверяйте шаблоны путей отдельно: перед настройкой Swagger убедитесь, что маршруты Ocelot работают корректно, делая прямые вызовы API.
2. Используйте версионированные API: включайте информацию о версии в конфигурацию Swagger, чтобы избежать конфликтов.
3. Проверяйте downstream‑Swagger: убедитесь, что Swagger downstream‑сервиса доступен и содержит валидные операции перед настройкой Ocelot.
4. Следите за обновлениями пакетов: держите MMLib.SwaggerForOcelot обновлённым, чтобы получать исправления ошибок и улучшения.
5. Соблюдайте единообразие имен: держите ключи Swagger, имена маршрутов и сервисов согласованными во всей конфигурации.
6. Тестируйте в изоляции: проверяйте каждый Swagger‑эндпоинт отдельно, прежде чем объединять несколько сервисов.

Источники

1. Stack Overflow – No operations defined in spec when using MMLib.SwaggerForOcelot to build combined swagger for Ocelot
2. Stack Overflow – Ocelot Swagger MMLib.SwaggerForOcelot showing “No operations defined in spec!”
3. GitHub – MMLib.SwaggerForOcelot Issue #19: All paths and definitions are removed from swagger.json
4. GitHub – MMLib.SwaggerForOcelot Issue #90: SwaggerEndPoints configuration section is missing or empty
5. Think Simple – Configure Swagger on api gateway using ocelot in asp.net core application
6. NuGet Gallery – MMLib.SwaggerForOcelot 9.0.0
7. GitHub – MMLib.SwaggerForOcelot Discussions #153: Programmatic attempt to add Swagger Endpoints

Вывод

Ошибка «No operations defined in spec!» в MMLib.SwaggerForOcelot обычно вызвана проблемами сопоставления шаблонов путей во время процесса трансформации Swagger. Чтобы решить эту проблему:

1. Исправьте переменные шаблонов пути, убедившись, что имена совпадают между upstream‑ и downstream‑шаблонами.
2. Настройте TransformByOcelotConfig в соответствии с вашими потребностями маршрутизации.
3. Проверьте полную конфигурацию маршрутов с необходимыми свойствами.
4. Проверьте совместимость версий пакетов и при необходимости откатитесь к более стабильным версиям.
5. Используйте прямые шаблоны пути вместо переменных, если это возможно.

Решив эти конфигурационные вопросы, вы сможете корректно отображать операции Swagger в объединённой документации Ocelot, сохраняя правильную маршрутизацию upstream‑путей. Если проблема сохраняется, рассмотрите возможность реализации пользовательской логики трансформации или использования отдельных Swagger‑ключей для разных сервисов.