# swagger-ui-spring-boot-starter

**Repository Path**: guaoran/swagger-ui-spring-boot-starter

## Basic Information

- **Project Name**: swagger-ui-spring-boot-starter
- **Description**: 开发 swagger-ui-spring-boot-starter 组件可以直接集成到 springboot 项目中，只需配置启动即可，增加 使用 spring-boot-starter-security 进行访问 swagger-ui.html 地址的权限认证，因为很多时候这些信息是不希望被外人看到的(并不会影响引用的工程）。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2019-07-26
- **Last Updated**: 2024-11-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 开启 swagger 组件

> 通过自动配置实现 `swagger-ui-spring-boot-starter` 组件，通过引用该 starter 并进行配置启动即可。
>
> 新增通过 `spring-boot-starter-security` 进行 `swagger-ui.html` 访问的权限控制。*不知道是我理解的问题还是实现的问题，由于通过apiKey 未达到我想限制 swagger 的访问，所以采用了该方式。*
>

1. 引用 `swagger-ui` 组件依赖

   ```xml
      <dependency>
          <groupId>com.guaoran.commons</groupId>
          <artifactId>swagger-ui-spring-boot-starter</artifactId>
          <version>${project.version}</version>
          <!--<version>0.0.1-SNAPSHOT</version>-->
      </dependency>
   ```

2. `application.properties`  中添加配置

   ```properties
   # swagger
   common.swagger.enabled=true
   common.swagger.base-package=com.guaoran
   common.swagger.title=农业大数据
   common.swagger.version=1.0
   common.swagger.description=通用API接口文档
   
   ## 排除多个请求路径或请求路径前缀
   common.swagger.exclude-path=/,/demo0/*
   
   ## 指定对所有人开发，即访问不需要用户名和密码
   #common.swagger.security-open-to-all=true
   
   ## swagger 使用 security 加密，默认 admin/admin
   common.swagger.security-user-name=admin
   common.swagger.security-user-password=123456
   
   ### 许可证
   #common.swagger.license=Apache License, Version 2.0
   #common.swagger.license-url=https://www.apache.org/licenses/LICENSE-2.0.html
   ### 服务条款
   #common.swagger.terms-of-service-url=http://www.gitee.com/guaoran
   ## 联系人
   #common.swagger.contact-name=guaoran
   #common.swagger.contact-url=http://www.gitee.com/guaoran
   #common.swagger.contact-email=guchengniuniu@163.com
   ```

## 多环境配置

> 该组件主要是自动装配 `swagger`，并通过 `spring-boot-starter-security` 进行权限的限制。
>
> 为什么要这样呢？主要是我的考虑是 `swagger-ui.html` 不希望被其他人看到，所以使用权限认证。

那么在真实的项目中可能会有多种情况。比如：

1. 项目中引用  `swagger-ui-spring-boot-starter`  ，直接开启配置即可

   ```properties
   common.swagger.enabled=true
   ```

   *当访问不需要密码时,即对所有人开放*

   ```properties
   common.swagger.enabled=true
   common.swagger.security-open-to-all=true
   ```

2. 项目中引用  `swagger-ui-spring-boot-starter`  ，但是也引用了 `spring-boot-starter-securtiy` 并配置了权限认证，不要担心，由于    `swagger-ui-spring-boot-starter`  在 `security` 配置中优先级较低，所以会以你自己的工程的配置为准的。

   *在配置中对 `swagger-ui.html` 的访问进行了用户角色的指定（默认是 `ROLE_SWAGGEER` ,用户名和密码都是 `admin`,当然你也可以指定它们)*

   ```properties
   ## 使用你工程中配置的 ROLE_USER 角色
   common.swagger.security-role-name=USER
   ## swagger 使用 security 加密，默认 admin/admin
   common.swagger.security-user-name=admin
   common.swagger.security-user-password=123456
   ```

3. 项目引用了 `swagger-ui-spring-boot-starter` ，工程中并没有关于 `security` 的配置，而且也没有在配置文件（`application.properties`）中开启(`common.swagger.enabled=true`)  ，（呃，你有点淘气了）。此时 `swagger` 功能是不会被装配的，但是会装配 `spring-boot-starter-securtiy` ，这时当你去访问你其他的工程时会发现会跳转到 `security` 的登录界面。

   所以有两种解决方式,

   * 第一种：不要淘气（既然不开启 `swagger` ，就把项目引用的 `swagger-ui-spring-boot-starter`  依赖去除）

   * 第二种：在 `springboot` 启动类中排除掉 `security` 功能的自动配置

     ```java
     @SpringBootApplication(exclude={SecurityAutoConfiguration.class, SecurityFilterAutoConfiguration.class, ManagementWebSecurityAutoConfiguration.class})
     
     @EnableEurekaClient //激活 eureka 客户端
     @EnableHystrix //激活 hystrix
     @EnableTransactionManagement(proxyTargetClass = true) //jpa
     public class NewsDataProviderApplication {
     
         public static void main(String[] args) {
             SpringApplication.run(NewsDataProviderApplication.class, args);
         }
     
     }
     ```

     

 ## 代码参考

引用 `swagger-ui-spring-boot-starter` 组件，[自定义 `security` 账号](https://gitee.com/guaoran/spring-cloud-applications/tree/master/agricultural-big-data)

引用 `swagger-ui-spring-boot-starter` 组件，[使用默认 `security` 账号或者淘气](https://gitee.com/guaoran/spring-cloud-applications/tree/master/services/news-data/news-data-service-provider)

引用 `swagger-ui-spring-boot-starter` 组件，[使用`spring-boot-starter-security` 权限配置](https://gitee.com/guaoran/spring-cloud-applications/tree/master/security-demo)