Spring Boot - Swagger 自定义请求头参数

Spring Boot 2.2.4.RELEASE

实现

新建 Spring Boot 项目，引入依赖：

<project>
    <properties>
        <java.version>1.8</java.version>
        <springfox-swagger2.version>2.9.2</springfox-swagger2.version>
        <springfox-swagger-ui.version>2.9.2</springfox-swagger-ui.version>
    </properties>

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

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-swagger2.version}</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-swagger-ui.version}</version>
        </dependency>
    </dependencies>
</project>

新建配置类，自定义一个 Authorization 请求头参数：

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

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.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    // API 文档地址：http://localhost:8080/swagger-ui.html
    
    @Bean
    public Docket docket() {
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<>();
        parameterBuilder.name("Authorization") // Updates the parameter name
            .description("JSON Web Token")
            .modelRef(new ModelRef("string"))
            .parameterType("header")
            .required(false)
            .build();
        parameters.add(parameterBuilder.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any()) // Any RequestHandler satisfies this condition
                .paths(PathSelectors.any()) // Any path satisfies this condition
                .build()
                .globalOperationParameters(parameters); // Adds default parameters which will be applied to all operations.
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder() // Builds the api information
                .title("Spring Boot API Document")
                .description("")
                .version("1.0.0")
                .build();
    }
}

新建控制器类：

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class IndexController {

    @GetMapping({"/"})
    public String index(HttpServletRequest request, HttpServletResponse response) {
        String authorization = request.getHeader("Authorization");
        System.out.println(authorization);
        return authorization;
    }
}

这里主要是获取请求头参数，然后将其返回。

启动项目，访问 http://localhost:8080/swagger-ui.html，查看 index-controller，可以看到我们自定义的请求头参数：

输入参数，发起请求：