Слияние кода завершено, страница обновится автоматически
Если изображение не отображается, 👉: Swagger официальный Starter с этим усилением действительно хорош!
В этой статье я просто расскажу вам, как использовать Swagger в проекте.
Что такое Swagger? Кратко говоря, Swagger — это набор открытых инструментов, основанных на стандарте OpenAPI, который помогает нам проектировать, создавать, документировать и использовать REST API.
Почему использовать Swagger? В условиях разделения фронтенда и бэкенда, наличие документации REST API значительно повышает нашу производительность. Фронтенд-разработчики могут легко понять параметры и возвращаемые значения каждого интерфейса, сравнивая их с документацией REST API. С помощью Swagger можно сгенерировать документацию REST API с интерфейсом пользователя, используя минимальное количество аннотаций, без необходимости ручного написания кода бэкендом. Кроме того, через этот интерфейс можно непосредственно тестировать соответствующие API, что упрощает подготовку сложных параметров запроса.
Основные моменты статьи:
Официальный Swagger3.0 уже имеет собственный Spring Boot Starter, который можно использовать, добавив один jar-файл (версия Spring Boot 2.3.6.RELEASE).
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
Нет необходимости в дополнительной настройке! Просто перейдите в браузере по адресу: http://ip:port/swagger-ui/ и вы увидите результат.
Если ваш проект использует Spring Security для аутентификации, вам нужно добавить Swagger-связанные URL в белый список.
String[] SWAGGER_WHITELIST = {
"/swagger-ui.html",
"/swagger-ui/*",
"/swagger-resources/**",
"/v2/api-docs",
"/v3/api-docs",
"/webjars/**"
};
@Override
protected void configure(HttpSecurity http) throws Exception {
http.cors().and()
// Отключение CSRF
.csrf().disable()
.authorizeRequests()
// swagger
.antMatchers(SWAGGER_WHITELIST).permitAll()
......
}
Кроме того, некоторые запросы требуют аутентификации для доступа. Для этого нам нужно выполнить некоторые базовые настройки для Swagger.
Способы настройки очень просты, я предлагаю два различных способа для использования.
С помощью этого способа нам нужно авторизоваться только один раз для использования всех требующих авторизации интерфейсов.
/**
* @author shuang.kou
* @description swagger-связанные настройки
*/
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("github.javaguide.springsecurityjwtguide"))
.paths(PathSelectors.any())
.build()
.securityContexts(securityContext())
.securitySchemes(securitySchemes());
}
private List<SecurityScheme> securitySchemes() {
return Collections.singletonList(new ApiKey("JWT", SecurityConstants.TOKEN_HEADER, "header"));
}
private List<SecurityContext> securityContext() {
SecurityContext securityContext = SecurityContext.builder()
.securityReferences(defaultAuth())
.build();
return Collections.singletonList(securityContext);
}
}
@Configuration
public class SwaggerConfig {
``````markdown
### Использование knife4j для улучшения Swagger
Согласно официальной документации, knife4j представляет собой улучшенное решение для интеграции Swagger с Java MVC-фреймворками для генерации API-документации.
```Проект доступен по адресу: [https://gitee.com/xiaoym/knife4j](https://gitee.com/xiaoym/knife4j).
Использование очень простое, достаточно добавить зависимость (версия SpringBoot 2.3.6.RELEASE).
```xml
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
После установки, перейдите по адресу: http://ip:port/doc.html.
Результат представлен ниже. Можно заметить, что по сравнению с оригинальным UI Swagger, это действительно выглядит более удобным и полезным.
```markdown
### Использование knife4j для улучшения Swagger
Согласно официальной документации, knife4j представляет собой улучшенное решение для интеграции Swagger с Java MVC-фреймворками для генерации API-документации.
Проект доступен по адресу: [https://gitee.com/xiaoym/knife4j](https://gitee.com/xiaoym/knife4j).
Использование очень простое, достаточно добавить зависимость (версия SpringBoot 2.3.6.RELEASE).
```xml
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
После установки, перейдите по адресу: http://ip:port/doc.html.
Результат представлен ниже. Можно заметить, что по сравнению с оригинальным UI Swagger, это действительно выглядит более удобным и полезным.
```
Кроме улучшений в пользовательском интерфейсе, Knife4j также предоставляет ряд функций, которые можно использовать сразу после установки.
Например: **поиск API-интерфейсов** (версия Knife4j > 2.0.1)
Еще пример: **экспорт оффлайн-документации**
С помощью Knife4j можно легко экспортировать документацию Swagger в различных форматах.
> - markdown: Экспорт текущего логического раздела со всеми интерфейсами в формате Markdown
> - html: Экспорт текущего логического раздела со всеми интерфейсами в формате Html
> - word: Экспорт текущего логического раздела со всеми интерфейсами в формате Word (с версии 2.0.5)
> - openapi: Экспорт текущего логического раздела в формате OpenAPI (с версии 2.0.6)
> - pdf: Не реализован
Пример экспорта в формате Html представлен ниже.
Что ж, не теряйте времени, попробуйте прямо сейчас!
Вы можете оставить комментарий после Вход в систему
Неприемлемый контент может быть отображен здесь и не будет показан на странице. Вы можете проверить и изменить его с помощью соответствующей функции редактирования.
Если вы подтверждаете, что содержание не содержит непристойной лексики/перенаправления на рекламу/насилия/вульгарной порнографии/нарушений/пиратства/ложного/незначительного или незаконного контента, связанного с национальными законами и предписаниями, вы можете нажать «Отправить» для подачи апелляции, и мы обработаем ее как можно скорее.
Опубликовать ( 0 )