【swagger】springboot项目中配置Swagger的两种方式以及swagger权限验证、安全控制

前言

swagger是什么？
    Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

    Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

一、springboot配置Swagger的两种方式

方式1：使用配置文件来配置Swagger设置

1.在pom.xml文件添加依赖

        <dependency><groupId>com.spring4all</groupId><artifactId>swagger-spring-boot-starter</artifactId><version>1.8.0.RELEASE</version></dependency>

2.在配置文件application.yml添加配置

swagger:base-package: 'com.itfuture.controller'base-path: '/**'title: '注解方式的Swagger'description: '这是注解方式的Swagger'version: '2.0'license-url: 'https://www.apache.org/licenses/LICENSE-2.0.html'license: 'The Apache License'contact:name: 'itfuture'url: 'https:www.baidu.com'email: '******@qq.com'

3.在启动类添加注解@EnableSwagger2Doc

@EnableSwagger2Doc
@SpringBootApplication
public class EApplication {public static void main(String[] args) {Object o=new Object();SpringApplication.run(EApplication.class, args);}}

4.如果报这个异常

5.在pom.xml添加如下依赖

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>

方式2：创建Java类来配置Swagger设置

1.在pom.xml添加依赖

        <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency>
<!--        导入swagger-ui依赖--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

2.创建Swagger的Java配置类(可以在配置类添加@EnableSwagger2注解，也可以在启动器类上加这个注解！)

/**swagger2配置* @author： wxh* @version：v1.0* @date： 2022/09/22 20:04*/
@Configuration
@EnableSwagger2
public class Swagger2Config {@Beanpublic Docket webApiConfig(){//添加head参数startArrayList<Parameter> pars = new ArrayList<>();ParameterBuilder tokenPar = new ParameterBuilder();tokenPar.name("userId").description("用户Id").defaultValue("1").modelRef(new ModelRef("string")).parameterType("header").required(false).build();pars.add(tokenPar.build());ParameterBuilder tmpPar = new ParameterBuilder();tmpPar.name("userTempId").description("临时用户ID").defaultValue("1").modelRef(new ModelRef("string")).parameterType("header").required(false).build();pars.add(tmpPar.build());//添加head参数endreturn new Docket(DocumentationType.SWAGGER_2).groupName("webApi").apiInfo(webApiInfo()).select()//可以测试请求头中：输入token.apis(RequestHandlerSelectors.basePackage("com.gg.zhschool.controller"))//.apis(RequestHandlerSelectors.withClassAnnotation(ApiOperation.class))//过滤掉admin路径下的所有页面//.paths(Predicates.and(PathSelectors.regex("/sms/.*")))//过滤掉所有error或error.*页面//.paths(Predicates.not(PathSelectors.regex("/error.*"))).build().globalOperationParameters(pars);}private ApiInfo webApiInfo(){return new ApiInfoBuilder().title("网站-API文档").description("本文档描述了网站微服务接口定义").version("1.0").contact(new Contact("itfuture","http://www.baidu.com","itfuture03@163.com")).build();}private ApiInfo adminApiInfo(){return new ApiInfoBuilder().title("后台管理系统-API文档").description("本文档描述了后台管理系统微服务接口定义").version("1.0").contact(new Contact("atguigu", "http://atguigu.com", "512111559@qq.com")).build();}}

3.在启动类添加注解@EnableSwagger2（如果在配置类已经加过则跳过此步）

@SpringBootApplication
@EnableSwagger2
public class ZhSchoolApplication {public static void main(String[] args) {SpringApplication.run(ZhSchoolApplication.class, args);}}

然后启动项目，在浏览器输入：http://localhost:8080/swagger-ui.html

二、swagger权限验证、安全控制

当我们使用swagger，进行文档管理的时候，担心文档暴露(暴露接口)不安全时。

可采用两种方式

1.环境权限配置

对swagger文档配置只在测试环境可访问，生产环境不可访问。

 @Profile({"dev","test"})

如以上配置，则只有在dev以及test环境有效，在生产环境不可访问。

2.账户权限配置

在1.9.0版本时,针对Swagger的资源接口,SwaggerBootstrapUi提供了简单的Basic认证功能。
如果是springboot项目可在yml文件配置

(1)在yml文件中配置

swagger:production: falsebasic:enable: trueusername: eSwaggerpassword: 123456

以上分别为启用，并且用户名为eSwagger.密码为123456。

切记swagger.production 不可设置为true，否则将屏蔽所有资源

(2)在swaggerConfig中添加注解

@EnableSwaggerBootstrapUI

结果就是此时访问需要通过用户密码才可进行访问!

此时只能通过配置的正确用户名和密码来登录！否则无法进入！