Как Изменить BaseUrl В Swagger UI: Подробное Руководство

Aug 5, 2025 by Mei Lin 57 views

Как изменить baseUrl в Springfox Swagger? Подробное руководство

Привет, ребята! В этой статье мы подробно разберем, как изменить baseUrl в Springfox Swagger, чтобы ваш Swagger UI был доступен по пользовательскому пути. Springfox Swagger — отличный инструмент для автоматического создания документации API для ваших Spring Boot приложений. Иногда вам может потребоваться настроить путь, по которому отображается пользовательский интерфейс Swagger, чтобы лучше соответствовать структуре вашего приложения или требованиям развертывания. В этом руководстве мы рассмотрим шаги, необходимые для достижения этого, и предоставим вам четкие примеры и объяснения.

Что такое Springfox Swagger?

Springfox Swagger — это библиотека, которая автоматизирует создание документации RESTful API для приложений Spring Boot. Он сканирует ваш код и генерирует спецификацию Swagger (OpenAPI), которую можно использовать для визуализации и взаимодействия с вашими API с помощью пользовательского интерфейса Swagger. Это невероятно полезно для разработчиков, позволяя им легко изучать и тестировать ваши API. Документирование API является важным аспектом разработки программного обеспечения, и Springfox Swagger значительно упрощает эту задачу. Благодаря возможности автоматического создания документации, разработчики могут тратить меньше времени на ручное создание документации и больше времени на фактическое создание API.

Проблема: Настройка baseUrl

По умолчанию Swagger UI доступен по адресу http://localhost:8090/swagger-ui/. Однако в некоторых случаях вам может потребоваться изменить этот адрес на что-то более настраиваемое, например http://localhost:8090/my/custom/path/. Это может быть необходимо для соответствия существующим соглашениям о маршрутизации вашего приложения, улучшения безопасности или просто для того, чтобы URL-адреса Swagger UI были более интуитивно понятными. Изменение baseUrl может оказаться непростой задачей, если вы не знакомы с конфигурацией Springfox Swagger. Вот тут-то и приходит на помощь это руководство. Мы проведем вас через различные методы и варианты, чтобы убедиться, что вы можете успешно настроить baseUrl в соответствии с вашими потребностями.

Итак, давайте сразу перейдем к делу. Вот как вы можете изменить baseUrl в Springfox Swagger:

Шаг 1: Добавьте зависимости Springfox Swagger

Во-первых, убедитесь, что в ваш проект добавлены необходимые зависимости Springfox Swagger. Если вы используете Maven, добавьте следующее в файл pom.xml:

 <dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>3.0.0</version>
 </dependency>
 <dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>3.0.0</version>
 </dependency>

Если вы используете Gradle, добавьте это в свой файл build.gradle:

 dependencies {
 implementation 'io.springfox:springfox-swagger2:3.0.0'
 implementation 'io.springfox:springfox-swagger-ui:3.0.0'
 }

Эти зависимости позволят вашему приложению Spring Boot использовать возможности Springfox Swagger для генерации и отображения документации API. Версии, указанные выше, являются последними стабильными версиями, но всегда проверяйте наличие каких-либо новых версий, когда вы внедряете эти зависимости в свои проекты. Убедитесь, что ваши зависимости правильно настроены, это важный первый шаг. Без этих зависимостей Swagger не будет работать должным образом.

Шаг 2: Настройте Springfox Docket

Далее вам нужно настроить Springfox Docket. Docket — это основной класс Springfox, который настраивает генерацию спецификации Swagger. Создайте класс конфигурации Spring, который настраивает Docket. Вот пример:

 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;

 @Configuration
 @EnableSwagger2
 public class SpringFoxConfig {
 @Bean
 public Docket api() {
 return new Docket(DocumentationType.SWAGGER_2)
 .select()
 .apis(RequestHandlerSelectors.any())
 .paths(PathSelectors.any())
 .build();
 }
 }

В этом коде мы создаем класс конфигурации SpringFoxConfig и используем аннотацию @EnableSwagger2, чтобы включить поддержку Swagger 2. Бин Docket настраивается для выбора всех API и путей. Это основная конфигурация, и она работает нормально, но если вы хотите настроить baseUrl, нам нужно внести некоторые изменения.

Шаг 3: Установите baseUrl

Чтобы установить baseUrl, вам необходимо изменить бин Docket. К сожалению, Springfox Swagger 2 не имеет прямого метода для установки baseUrl. Однако мы можем обойти это, настроив путь, по которому отображается пользовательский интерфейс Swagger. Это включает в себя переадресацию пользовательского интерфейса Swagger на ваш пользовательский путь.

Вот как вы можете это сделать:

Вариант 1: Использование WebMvcConfigurer

Вы можете использовать WebMvcConfigurer для перенаправления URL-адреса Swagger UI к вашему пользовательскому пути. Создайте класс, который реализует WebMvcConfigurer и переопределяет метод addViewControllers:

 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
 import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

 @Configuration
 public class SwaggerUIConfig implements WebMvcConfigurer {
 @Override
 public void addViewControllers(ViewControllerRegistry registry) {
 registry.addRedirectViewController("/my/custom/path/swagger-ui.html", "/swagger-ui/index.html");
 registry.addRedirectViewController("/my/custom/path/", "/swagger-ui/index.html");
 }

 @Override
 public void addResourceHandlers(ResourceHandlerRegistry registry) {
 registry.addResourceHandler("/my/custom/path/**")
 .addResourceLocations("classpath:/META-INF/resources/");
 }
 }

В этом коде мы перенаправляем /my/custom/path/swagger-ui.html и /my/custom/path/ на /swagger-ui/index.html. Мы также добавляем обработчик ресурсов для обслуживания статических ресурсов пользовательского интерфейса Swagger из classpath. С помощью этой конфигурации при обращении к http://localhost:8090/my/custom/path/ вы будете перенаправлены на пользовательский интерфейс Swagger.

Вариант 2: Использование application.properties или application.yml

Другой способ изменить baseUrl — настроить путь контекста сервера в вашем файле application.properties или application.yml. Это изменит базовый путь для всего приложения, включая пользовательский интерфейс Swagger.

В вашем файле application.properties:

 server.servlet.context-path=/my/custom/path

Или, если вы используете application.yml:

 server:
 servlet:
 context-path: /my/custom/path

Установив context-path, вы эффективно измените baseUrl для всего приложения. Теперь пользовательский интерфейс Swagger будет доступен по адресу http://localhost:8090/my/custom/path/swagger-ui/. Этот метод более глобален и влияет на все конечные точки в вашем приложении, поэтому его следует использовать с осторожностью, чтобы не вызвать непредвиденных последствий.

Вариант 3: Использование Reverse Proxy

В производственной среде обычно рекомендуется использовать обратный прокси-сервер, такой как Nginx или Apache, для управления маршрутизацией и обслуживанием статических ресурсов. С помощью обратного прокси-сервера вы можете отобразить пользовательский путь на пользовательский интерфейс Swagger без внесения каких-либо изменений в код вашего приложения. Этот подход обеспечивает большую гибкость и контроль, особенно при работе с несколькими приложениями и доменами.

Вот пример того, как вы можете настроить Nginx для проксирования запросов к пользовательскому интерфейсу Swagger:

 location /my/custom/path/ {
 proxy_pass http://localhost:8090/swagger-ui/;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 }

В этой конфигурации Nginx любые запросы к /my/custom/path/ будут перенаправлены на http://localhost:8090/swagger-ui/. Это означает, что пользовательский интерфейс Swagger будет доступен по адресу http://yourdomain.com/my/custom/path/. Обратные прокси-серверы, такие как Nginx, очень эффективны для управления маршрутизацией и обеспечивают дополнительный уровень безопасности и производительности. Они позволяют разгружать задачи, такие как SSL-шифрование и сжатие, из ваших серверных приложений.

Шаг 4: Проверьте конфигурацию

После внесения изменений запустите свое приложение Spring Boot и перейдите к пользовательскому URL-адресу (http://localhost:8090/my/custom/path/ в наших примерах). Если все настроено правильно, вы должны увидеть пользовательский интерфейс Swagger, отображающийся по новому базовому URL-адресу. Важно тщательно протестировать, чтобы убедиться, что все ресурсы и конечные точки загружаются правильно. Если вы столкнулись с какими-либо проблемами, проверьте журналы вашего приложения и конфигурации обратного прокси-сервера (если применимо) на наличие каких-либо ошибок или неверных конфигураций.

Иногда что-то идет не так, как планировалось. Вот несколько советов по устранению неполадок, которые помогут вам диагностировать и решить общие проблемы:

Очистите кэш браузера: Иногда ваш браузер может кэшировать старые версии статических ресурсов. Очистка кэша браузера может решить проблемы с отображением пользовательского интерфейса Swagger.
Проверьте журналы приложения: Журналы вашего приложения — ценный источник информации. Ищите любые ошибки или предупреждения, связанные с Springfox Swagger или конфигурацией перенаправления.
Убедитесь, что зависимости правильные: Убедитесь, что вы добавили правильные зависимости Springfox Swagger в свой проект, и что версии совместимы с вашей версией Spring Boot.
Проверьте конфигурации: Дважды проверьте свои классы конфигурации и файлы свойств, чтобы убедиться, что все настроено правильно. Типичные ошибки включают опечатки в путях или неправильные настройки.
Используйте инструменты разработчика: Инструменты разработчика вашего браузера могут помочь вам проверить сетевые запросы и ответы. Это может помочь вам определить, загружаются ли статические ресурсы правильно и перенаправляются ли API-запросы должным образом.

Отлично, ребята! Вы успешно изменили baseUrl в Springfox Swagger. Как видите, есть несколько способов добиться этого, в зависимости от ваших конкретных потребностей и среды. Независимо от того, используете ли вы WebMvcConfigurer, настраиваете ли путь контекста сервера или используете обратный прокси-сервер, теперь у вас есть инструменты для настройки пользовательского интерфейса Swagger в соответствии с вашими требованиями. Надеюсь, это руководство было полезным и поможет вам более эффективно документировать свои API. Помните, что хорошо документированные API необходимы для поддержания и принятия, поэтому прилагайте дополнительные усилия, чтобы сделать их доступными и простыми в использовании. Продолжайте строить замечательные API!

Дополнительные ресурсы

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

Официальная документация Springfox: Всегда хорошее место для начала. Он содержит подробную информацию о возможностях и вариантах конфигурации Springfox.
Документация Swagger: Узнайте больше о спецификации Swagger и инструментах, доступных для разработки API.
Документация Spring Boot: Узнайте больше о настройках и возможностях Spring Boot.
Обратные прокси-серверы (Nginx, Apache): Изучите, как настраивать обратные прокси-серверы для улучшения производительности и безопасности.

Спасибо за чтение и удачной разработки!