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

Posted 2022-06-30 bug菌¹

👨‍🎓作者：bug菌

✏️博客：CSDN、掘金等

💌公众号：猿圈奇妙屋

🚫特别声明：原创不易，转载请附上原文出处链接和本文声明，谢谢配合。

🙏版权声明：文章里可能部分文字或者图片来源于互联网或者百度百科，如有侵权请联系bug菌处理。

一、前言🔥

环境版本：idea2019.3 + springboot2.3

二、背景🔥

        说起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进行接口测试了。

... ...

        好啦，以上就是这期的全部内容啦，如果对你有所帮助，还请不要忘记给bug菌[三连支持]哟。如果想获得更多的学习资源或者想和更多的技术爱好者一起交流，可以关注我的公众号『猿圈奇妙屋』，后台回复关键词领取学习资料、大厂面经、面试模板等海量资源，就等你来拿。

五、文末🔥

        如果你还想要学习更多，小伙伴们大可关注bug菌专门为你们创建的专栏《SpringBoot零基础入门》，都是我一手打下的江山，持续更新中，希望能帮助到更多小伙伴们。

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

最后送大家两句话，与诸君共勉！

---

☘️做你想做的人，没有时间限制，只要愿意，什么时候都可以start，

🍀你能从现在开始改变，也可以一成不变，这件事，没有规矩可言，你可以活出最精彩的自己。

---

​​​

💌如果文章对您有所帮助，就请留下您的赞吧！(#^.^#)；

💝如果喜欢bug菌分享的文章，就请给bug菌点个关注吧！(๑′ᴗ‵๑)づ╭❤～；

💗如果对文章有任何疑问，还请文末留言或者加群吧【QQ交流群:708072830】；

💞鉴于个人经验有限，所有观点及技术研点，如有异议，请直接回复参与讨论(请勿发表攻击言论，谢谢）；

💕版权声明：原创不易，转载请附上原文出处链接和本文声明，版权所有，盗版必究！！！谢谢。