Swagger идентифицирует редкие конечные точки в REST API - PullRequest
Новая
       98

Swagger идентифицирует редкие конечные точки в REST API

1 голос
/ 25 октября 2019

Несколько дней назад я запустил REST API в JavaEE 7, реализовал один класс с тремя методами и успешно реализовал Swagger и Swagger-UI в проекте, который показал три конечные точки, которые я успешно реализовал в сгенерированном JSON.

Однако я перешел на JavaEE 8, и после этого изменения Swagger обнаруживает несколько неизвестных конечных точек, например, «по умолчанию» (этот захват показывает только часть их всех):

Some endpoints

Исследуя немного, я обнаружил, что эти конечные точки могут принадлежать API-интерфейсу REST JPA в реализации Eclipselink, как описано здесь https://oracle -base.com / article / misc / oracle-rest-data-services-ords-open-api-swagger-support и здесь https://www.eclipse.org/eclipselink/documentation/2.4/solutions/restful_jpa004.htm#CHDFCFFA Несмотря на то, что они появляются в сгенерированном JSON, все они содержат пути переменных, поэтому я не могу получить к ним доступ по пути, указанному Swagger, дажеПридумывая некоторые параметры, такие как «версия», используя приведенные выше примеры.

Используемая мной версия Swagger - v3, она же версия OpenAPI. Я указываю свойства OpenAPI с @OpenAPIDefinition в классе конечных точек, который также содержит аннотацию @Tag для их группировки, а три метода содержат тег @Operation со своими собственными @ApiResponse. Больше нет написанных мной аннотаций / файлов / классов Swagger / OpenAPI.

Вопрос в том, как заставить Swagger игнорировать эти конечные точки? Спасибо

1 Ответ

1 голос
/ 25 октября 2019

Наконец-то я нашел решение. Дело в том, что движок сканера Swagger сканирует весь проект, игнорируя, имеет ли класс и его методы @Operation или нет. Если моя гипотеза верна, некоторые классы Eclipselink могут иметь аннотации Swagger (я не уверен), поэтому, когда Swagger сканирует if, находит их и добавляет их в JSON / YAML. Решением является создание / добавление в существующий файл openapi.yaml (он может иметь несколько имен и может находиться в нескольких местах, как перечислено здесь: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-configuration#known-locations) this: 

resourceClasses:
- com.path.to.your.package.Resource
prettyPrint: true
cacheTTL: 0 
scannerClass: io.swagger.v3.jaxrs2.integration.JaxrsAnnotationScanner
readAllResources: false

Вместо resourceClasses это может быть написано resourcePackages, а затем должно быть указано весь пакет и класс в том же стиле, что и для определения пакета. Честно говоря, это свойство не влияет на мою проблему. Решение приходит при установкеreadAllResources до false. Причина здесь в примечании: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#operation

Примечание к блоку Примечание: механизм чтения swagger-jaxrs2 по умолчанию включает также методы отсканированных ресурсов, которые не помечены@Operation, если jax-rs @Path определен на уровне класса и / или метода, вместе с аннотацией метода http (@GET, @POST и т. Д.).

Я надеюсь, что этоРешение подходит для всех, кто сталкивается с той же проблемой.

...