Все еще интегрируете Swagger вручную? Swagger официальный Starter действительно ароматный!

Spring Boot Java
Все еще интегрируете Swagger вручную? Swagger официальный Starter действительно ароматный!

Адрес фактического центра электронной коммерции SpringBoot (40k+star):GitHub.com/macro-positive/…

Резюме

Интеграция Swagger в предыдущие проекты осуществлялась напрямую через зависимостиspringfox-swagger,springfox-swagger-uiОн реализован двумя jar-пакетами.Недавно я обнаружил, что версия springfox 3.0.0 уже имеет собственный SpringBoot Starter, который больше соответствует проекту SpringBoot.Это очень удобно и рекомендуется всем!

Используйте официальный Стартер

Давайте сначала воспользуемся официальным Starter для интеграции Swagger, чтобы убедиться, что это достаточно просто!

  • первый вpom.xmlДобавьте официальную зависимость Swagger от springfox;
<!--springfox swagger官方Starter-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
  • Добавьте Java-конфигурацию Swagger, настройте информацию API и путь сканирования класса, необходимый для создания документа интерфейса;
/**
 * Swagger2API文档的配置
 */
@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("mall-tiny")
                .contact(new Contact("macro", null, null))
                .version("1.0")
                .build();
    }
}
  • Чтобы получить доступ к информации о документации по API, перейдите по адресу:http://localhost:8088/swagger-ui/

  • Два шага, чтобы получить Swagger, интегрированный в SpringBoot, это очень просто!

по сравнению с предыдущей версией

Прежде чем мы использовали версию Springfox 2.9.2, сравните использование SpringBoot Starter 3.0.0, чтобы увидеть, в чем разница!

  • Старые версии требуют зависимостейspringfox-swagger2иspringfox-swagger-uiДве конфигурации, новую версию можно сделать одним Стартером, и если предыдущая версия не использует новую версиюswagger-modelsиswagger-annotationsЗависимость, появится интерфейс доступаNumberFormatExceptionпроблема;
<dependencies>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <exclusions>
            <exclusion>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-annotations</artifactId>
            </exclusion>
            <exclusion>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-models</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
    </dependency>
    <!--解决Swagger 2.9.2版本NumberFormatException-->
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.6.0</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.6.0</version>
    </dependency>
</dependencies>

  • В новой версии удалены некоторые сторонние зависимости, в том числеguava, при использовании старой версии ранее из-заguavaПроблемы с версиями привели к конфликтам зависимостей, подробности см. ниже.«Я обновил Swagger до новой версии, но не ожидал, что будет столько ям! 》;

  • Путь доступа к новой версии и старой версии документа изменился.Новая версия:http://localhost:8088/swagger-ui/, старая версия была:http://localhost:8088/swagger-ui.html

  • В новой версии добавлены некоторые конфигурации SpringBoot,springfox.documentation.enabledКонфигурация может контролировать, следует ли включать функцию создания документов Swagger;

  • Например, мы хотим толькоdevсреду, чтобы включить документацию Swagger, в то время как вprodЯ не хочу включать его в среде, мы можем пройти старую версию@ProfileРеализация аннотаций;
@Configuration
@EnableSwagger2
@Profile(value = {"dev"})
public class Swagger2Config {
    
}
  • Для новой версии мы можем настроить его в файле конфигурации SpringBoot.springfox.documentation.enabledсуществуетapplication-dev.ymlНастроен на true, вapplication-prod.ymlнастроен на ложь.

Интеграция использования Spring Security

Мы часто используем Spring Security для реализации аутентификации при входе в наши проекты.Далее давайте поговорим о том, как использовать Swagger для интеграции Spring Security для доступа к интерфейсам, требующим аутентификации при входе.

  • Как получить доступ к интерфейсу, который требует аутентификации при входе? Просто добавьте легальный при доступе к интерфейсуAuthorizationЗаголовка запроса достаточно, и ниже приведена конфигурация, связанная с Swagger;
/**
 * Swagger2API文档的配置
 */
@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
                .paths(PathSelectors.any())
                .build()
                //添加登录认证
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("mall-tiny")
                .contact(new Contact("macro", null, null))
                .version("1.0")
                .build();
    }

    private List<SecurityScheme> securitySchemes() {
        //设置请求头信息
        List<SecurityScheme> result = new ArrayList<>();
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
        result.add(apiKey);
        return result;
    }

    private List<SecurityContext> securityContexts() {
        //设置需要登录认证的路径
        List<SecurityContext> result = new ArrayList<>();
        result.add(getContextByPath("/brand/.*"));
        return result;
    }

    private SecurityContext getContextByPath(String pathRegex) {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex(pathRegex))
                .build();
    }

    private List<SecurityReference> defaultAuth() {
        List<SecurityReference> result = new ArrayList<>();
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        result.add(new SecurityReference("Authorization", authorizationScopes));
        return result;
    }
}
  • Нам нужно настроить несанкционированный доступ к статическим ресурсам Swagger в Spring Security, например, к пути доступа к домашней странице./swagger-ui/;
/**
 * SpringSecurity的配置
 * Created by macro on 2018/4/26.
 */
@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Autowired
    private UmsAdminService adminService;
    @Autowired
    private RestfulAccessDeniedHandler restfulAccessDeniedHandler;
    @Autowired
    private RestAuthenticationEntryPoint restAuthenticationEntryPoint;

    @Override
    protected void configure(HttpSecurity httpSecurity) throws Exception {
        httpSecurity.csrf()// 由于使用的是JWT，我们这里不需要csrf
                .disable()
                .sessionManagement()// 基于token，所以不需要session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                .and()
                .authorizeRequests()
                .antMatchers(HttpMethod.GET, // 允许对于网站静态资源的无授权访问
                        "/",
                        "/swagger-ui/",
                        "/*.html",
                        "/favicon.ico",
                        "/**/*.html",
                        "/**/*.css",
                        "/**/*.js",
                        "/swagger-resources/**",
                        "/v2/api-docs/**"
                )
                .permitAll()
                .antMatchers("/admin/login")// 对登录注册要允许匿名访问
                .permitAll()
                .antMatchers(HttpMethod.OPTIONS)//跨域请求会先进行一次options请求
                .permitAll()
                .anyRequest()// 除上面外的所有请求全部需要鉴权认证
                .authenticated();
        // 省略若干配置......
    }
}
  • Вызовите интерфейс входа в систему, чтобы получить токен, пароль учетной записиadmin:123456;

  • нажмитеAuthorizeВойти после кнопкиAuthorizationзаголовок запроса, а затем вы можете получить доступ к интерфейсу, который требует аутентификации входа.

Суммировать

Официальный Swagger Starter решает ряд проблем при интеграции Swagger ранее, упрощает процесс интеграции Swagger с SpringBoot и более удобен в использовании. В то же время в использовании некоторых сложных конфигураций практически нет изменений, и некоторые предыдущие методы использования все еще могут быть использованы!

Адрес исходного кода проекта

GitHub.com/macro-positive/…

Эта статьяGitHubGitHub.com/macro-positive/…Записано, приветствую всех на Star!

Категории