如何在swagger2中配置header请求头等参数信息？(若不会，我便手把手教你)

bug菌
5,992 阅读6分钟

👨‍🎓作者：bug菌
✏️博客：CSDN、掘金、infoQ、51CTO等
🎉简介：CSDN博客专家，C站历届博客之星Top50，掘金/InfoQ/51CTO等社区优质创作者，全网合计8w粉+，对一切技术感兴趣，重心偏Java方向；硬核公众号「 猿圈奇妙屋」，欢迎小伙伴们的加入，一起秃头，一起变强。
..
✍️温馨提醒：本文字数：1999字, 阅读完需：约 5 分钟

       嗨，家人们，我是bug菌呀，我又来啦。今天我们来聊点什么咧，OK，接着为大家更《springboot零基础入门教学》系列文章吧。希望能帮助更多的初学者们快速入门！

       小伙伴们在批阅文章的过程中如果觉得文章对您有一丝丝帮助，还请别吝啬您手里的赞呀，大胆的把文章点亮👍吧，您的点赞三连(收藏⭐+关注👨‍🎓+留言📃)就是对bug菌我创作道路上最好的鼓励与支持😘。时光不弃🏃🏻‍♀️，创作不停💕，加油☘️

一、前言🔥

环境说明：Windows10 + Idea2021.3.2 + Jdk1.8 + SpringBoot 2.3.1.RELEASE

二、背景🔥

        说起swagger，很多小伙伴肯定都对swagger都并不陌生，一个超级好用的集成在项目里的postman，但对于一般接口测试来说，是非常简便的。

       常规都是body参数体，别的也不会用到。然而，对于一些非"常"操作，就显得不是那么的熟悉使用了，但是基本了解了它所提供的api，你也能改它的源码，但是我今天要说的是既不要你熟悉它的的实现源码也不用额外学习其他技术，只需要看我写的，我就能教懂你今天的主题，"如何给swagger请求时能附带自定义的请求头？"。

       这个需求很常见吧，比如你的登录，如果是用token认证，那肯定会做的一件事就是每一次http请求都会要求前端在请求时请求头附带token令牌，对不对，这也是业务系统常用的登录拦截功能。今天我就拿这个例子来说，具体如何写，非常之简单。

三、解决方案🔥

       集成过swagger 的小伙伴，肯定都会在自己的项目中配置一下SwaggerConfig.java，缺它，你的swagger也运行不了，对吧。

       那么跟swagger添加自定义请求头有啥联系？别着急，继续往下看。

       我们都知道，body参数是自带的，要如果要添加header参数呢？那就要你手动添加啦，你只需要在注入该globalOperationParameters()，这是一个全局参数配置，你只需要将你设置的header 参数名设置进去即可。

我们先来看下 globalOperationParameters() 方法加在哪里。

    /**
     * swagger文档配置
     */
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.review.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters();// 全局配置
    }

       接着你既可以在当前类中把你要设置的header参数传进去，我是单独封装了一个添加参数的内置方法，这样好处就是代码不会造成过长。

    /**
     * 添加head参数配置
     */
    private List<Parameter> getParameterList() {
        ParameterBuilder clientIdTicket = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        clientIdTicket.name(Constant.TOKEN_HERDER_KEY).description("token令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false).build(); //设置false，表示clientId参数 非必填,可传可不传！
        pars.add(clientIdTicket.build());
        return pars;
    }

       假如你要添加多个header 请求头参数，那你就再new 一个 ParameterBuilder()类，然后一样的设置，在pars集合中将你参数build后add进去即可。Constant是我定义的一个常量类，这个你们若是不习惯直接定义字符串命名也可。

最后一步就是将此刻封装的header 头传入到全局配置方法中。

.globalOperationParameters(this.getParameterList());

       大家能看的明白不？若不能，我再把swagger配置全部粘贴到下边，大家好好的连串解读一下，基本看完我说的，你们下一次若是遇到再header添加自定义请求头的话，直接怼它，这我未出生就会了。

如下是完整swagger 配置。

package com.example.review.config;

import com.example.review.util.Constant;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;


/**
 * swagger配置
 *
 * @Author
 * @Date 2021-06-01 13:00
 */
@Configuration //必须存在
@EnableSwagger2 //必须存在
public class SwaggerConfig {

    /**
     * swagger文档配置
     */
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.review.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(this.getParameterList());// 全局配置
    }


    /**
     * 添加head参数配置
     */
    private List<Parameter> getParameterList() {
        ParameterBuilder clientIdTicket = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        clientIdTicket.name(Constant.TOKEN_HERDER_KEY).description("token令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false).build(); //设置false，表示clientId参数 非必填,可传可不传！
        pars.add(clientIdTicket.build());
        return pars;
    }


    /**
     * api相关配置
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger 接口文档")
                .contact(new Contact("review", "", ""))
                .description("swagger-bootstrap-ui")
                .termsOfServiceUrl("http://localhost:8888/")
                .version("1.0")
                .build();
    }

}

四、测试🔥

配置后，重启下项目刷新一下swagger 访问链接。诺，这不加的header类型就出来了么。是不是很简单，直接配置也就不需要所有人都跑去postman进行接口测试了。

​       ... ...

       ok，以上这样就好啦，如果还想学习更多，你可以看看我的往期热文推荐哦，每天积累一个奇淫小知识，日积月累下去，你一定能成为令人敬仰的大佬的。好啦，咱们下期见~

五、往期推荐🔥

文末🔥

如果还想要学习更多，小伙伴们可关注bug菌专门为大家创建的专栏《springboot零基础入门教学》，从无到有，从零到一！希望能帮助到更多小伙伴们。

我是bug菌，一名想走👣出大山改变命运的程序猿。接下来的路还很长，都等待着我们去突破、去挑战。来吧，小伙伴们，我们一起加油！未来皆可期，fighting！

感谢认真读完我博客的铁子萌，在这里呢送给大家一句话，不管你是在职还是在读，绝对终身受用。
时刻警醒自己：
抱怨没有用，一切靠自己；
想要过更好的生活，那就要逼着自己变的更强，生活加油！！！

avatar
文章
阅读
粉丝