Невозможно загрузить определение внешнего API - PullRequest
Новая
       23

Невозможно загрузить определение внешнего API

0 голосов
/ 09 июля 2019

Мы используем SwaggerEditor для написания спецификаций API OAS3.Теперь мы хотели бы перейти к более организованной настройке, где мы перемещаем общие определения, которые часто используются (например, некоторые параметры, ошибки, типы объектов), в некоторый общий файл, на который ссылаются другие API .

OAS3 поддерживает это, используя обычное ключевое слово $ref, например: 

$ref: "http://example.com/shared.yaml#/components/schemas/Person"

То, что мы пробовали до сих пор

  • Мы используем абсолютURL , т.е. не относительный путь.

  • Мы запускаем SwaggerEditor с параметром запроса url=, указывающим на наш файл спецификации.

    -> УказанныйURL общего файла API отображается в части редактора Swagger UI (справа) под заголовком API службы, поэтому, похоже, это работает.

  • Ссылка, на которую я пыталсяЯ использую абсолютный URL-адрес для файла YAML, который я размещаю на той же машине, что и редактор swagger (в Apache Tomcat).Например:

    $ref: "http://127.0.0.1:8080/foo/bar.yaml#/components/schemas/Person"

Мне удается запустить SwaggerEditor без ошибки CORS (это часто встречается при поиске этой проблемы, а также с нами в первую очередь).Я могу проверить в консоли браузера:

  • Внешний файл YAML фактически отправлен с необходимым заголовком CORS (Access-Control-... *)
  • В консоли браузера нет других ошибок.

НО внешняя ссылка по-прежнему не разрешена : редактор фактически не проверяет, является ли данное определение (в приведенном выше примере Person)существует - поэтому, если я ссылаюсь на какое-то поддельное слово, ошибка не отображается.Кроме того, интерактивная часть пользовательского интерфейса Swagger справа не отображает связанный тип должным образом ... Т.е. он не работает должным образом.

Не проблема CORS

(Сначала мы тоже столкнулись с этой проблемой, но теперь решили ее, выполнив следующие шаги.)

  • Я удостоверился в установке соответствующих заголовков CORS для общего YAML (bar.yaml выше), т.е. установите фильтр в web.xml Apache Tomcat.Я проверил, что запрос к файлу YAML получает заголовки CORS - я получаю ...

    Access-Control-Allow-Origin *

  • При открытии SwaggerEditor не забудьте очиститьСначала кешируется браузер, поскольку может случиться так, что браузер по-прежнему будет кэшировать запрос к указанному внешнему файлу YAML и таким образом запоминает отсутствующий заголовок CORS.Это может привести к тому, что SwaggerEditor отобразит ошибку CORS 1 , , даже несмотря на то, что на сервере тем временем обслуживается указанный ресурс с правильным заголовком .Более подробную информацию об ошибке можно также найти в консоли разработчика браузера 2 .

  • После очистки кэша мой SwaggerEditor снова корректно загрузил файл, увидел заголовок CORS иперестал выдавать ошибку CORS.

1 Это ошибка, отображаемая editor.swagger.io:

Ошибки

Ошибка выборки
Не удалось получить http://127.0.0.1:8080/foo/bar.yaml

Ошибка выборки
Возможна ли проблема перекрестного происхождения (CORS)?Источник URL (http://127.0.0.1:8080) не соответствует странице (http://editor.swagger.io). Проверьте, что сервер возвращает правильные заголовки 'Access-Control-Allow- *'.

2 Ошибка, отображаемая консолью JS браузера при попытке загрузить API с внешней ссылкой:

Доступ к выборке в 'http://127.0.0.1:8080/foo/bar.yaml' от источника' http://editor.swagger.io' был заблокирован политикой CORS: в запрашиваемом ресурсе отсутствует заголовок «Access-Control-Allow-Origin». Если непрозрачный ответ удовлетворяет ваши потребности, установите режим запроса «no-cors» для извлечения ресурса с помощью CORSотключено.

1 Ответ

0 голосов
/ 11 июля 2019

Мне удалось наконец решить нашу проблему. При вызове SwaggerEditor мы использовали неверный параметр запроса.

Чтобы правильно загрузить (и разрешить) внешнюю спецификацию YAML, следует использовать параметр запроса configUrl (не url!). Например: 

http://127.0.0.1:8080/swagger-editor-master/?configUrl=http://127.0.0.1:8080/foo/bar.yaml

Где ...

  • http://127.0.0.1:8080/swagger-editor-master/ указывает на редактора Swagger, а
  • http://127.0.0.1:8080/foo/bar.yaml указывает на файл спецификации, на который мы хотим сослаться из того, что мы сейчас редактируем в редакторе Swagger.

Используется как ссылка на внешнюю спецификацию, например, 

$ref: "http://127.0.0.1:8080/foo/bar.yaml#/components/schemas/Payment"

будет правильно разрешен в пользовательском интерфейсе Swagger справа (например, в разделе Схемы ссылочные свойства могут быть расширены и т. Д.). Однако кажется, что редактор не выдает ошибку, если задана недопустимая внешняя ссылка (вместо этого пользовательский интерфейс Swagger просто показывает «пустой» объект).

...