Swagger配置详解--教你玩转Swagger

1、引入依赖<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency>&lt

See you !

7175人浏览 · 2021-01-31 11:12:13

See you ! · 2021-01-31 11:12:13 发布

文章目录

本文介绍

本文主要介绍了swagger的常用配置，涉及无token，局部token，全局token，环境限制，多人开发等模块，基本满足项目中的所有使用。

基本配置流程（无token）

1. 引入依赖

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

2. 创建配置类

@EnableSwagger2 开启配置

@Configuration
@EnableSwagger2
public class MySwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * 多人开发可以设置多个Docket
     * @return
     */
    @Bean
    public Docket createRestApi(Environment environment) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo())
                .groupName("小组管理系统")
                //false 则不能在浏览器访问，true为默认。
                .enable(true)
                .select()
                //配置扫描接口的方式，基于包去扫描
                .apis(RequestHandlerSelectors.basePackage("com.marchsoft.group.manager.system.controller"))
                //paths()过滤什么路径
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("springboot利用swagger构建api文档")
                .description("基于小组管理的学生管理员系统")
                .termsOfServiceUrl("https://XXXX/XXXXX/group-manager/tree/develop/")
                .version("1.0")
                .build();
    }
}

3.创建实体类

@ApiModel(value="学生DTO对象", description="返回所有S学生最基本的信息") 作用在模型上，介绍当前模型

@ApiModelProperty(value = "id") 介绍当前模型的某个属性

4. 创建接口

介绍当前接口的基本信息，及作者

@ApiOperation(value = "获取某一学生的详细信息",notes = " \n author：zhangh")

介绍当前接口的参数

@ApiImplicitParams({@ApiImplicitParam(name = "id",value = "")})

	接口一：前端传递一个id
    @ApiOperation(value = "获取某一学生的详细信息",notes = " \n author：zhangh")
    @ApiImplicitParams({
            	@ApiImplicitParam(name = "id",value = "")
    })
    @PreAuthorize("hasAuthority('super_admin')")
    @GetMapping("/{id}")
    public Result getStudent(@PathVariable("id")    Long id) {
        StudentDTO student = studentService.getStudent(id);
        return Result.success(student);
    }
    
    接口二：  用于展示使用     前端传递的是一个对象
        @PutMapping("/update")
    public Result updateStudent(@RequestBody StudentDTO studentDTO){
        return null;
    }

5. 测试使用(无token)

在无token的情况下，我们配置到这里既能实现基本的功能了。

启动服务，访问swagger路径：

http://localhost:9898/swagger-ui.html

配置token

如果我们的系统中使用了token，那么在swagger测试时，毫无疑问，也是需要添加的。接下来介绍token添加的两种方法。

局部token

我们需要手动给每个接口都添加token信息。麻烦！

原理

调用Docket的globalOperationParameters()方法，并传入token基本配置信息

配置使用：

this.apiInfo()这个方法在基本配置（无token中有源码，这里就不重复添加了）

globalOperation()详情

    /***
     * @Author 
     * @Description  单一配置token
     * @Data 23:38 2021/1/29
     * @param
     * @return java.util.List<springfox.documentation.service.Parameter>
     */
    private List<Parameter> globalOperation(){
        //添加head参数配置start
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        //第一个token为传参的key，第二个token为swagger页面显示的值
        tokenPar.name("Authorization")
                .description("token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                //token前缀
                .defaultValue("Bearer ")
                .required(false).build();
        pars.add(tokenPar.build());
        return pars;
    }

测试使用

配置对照

传递对象

查看详情

全局token

刚刚我们配置了局部token，虽然我们能满足使用，但是过于麻烦，接下来我们配置一下全局token。

原理:

使用Docket提供的配置方案和配置上下文的两个方法。

使用步骤

在docket中配置上述两个方法，并传入参数

两个方法的配置信息：

    //设置基本的介绍信息
    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeyList = new ArrayList<>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
        return apiKeyList;
    }
    //过滤不需要进行验证的页面
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        //带有auth的页面将不用提供token即可访问。
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }
    //全局的token配置
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

测试使用

扩展使用

1.正式环境下不可使用接口文档

系统通常分为三种环境，开发环境（dev），测试环境（test），正式上线（pro）。
接口测试只能在dev和test环境下进行，正式上线后是严禁进行接口测试的。
swagger也为我们提供了相应，我们可以在dev和test环境下测试，pro环境下不能进行测试。

配置方式

 //在开发或者测试服务器使用swagger，正式环境没有swagger
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");
        boolean flag = environment.acceptsProfiles(profiles);