在前后端分离开发模式下,java服务端使用swagger为前端提供接口列表说明已经成为最佳实践,并且也可以用swagger作为服务端开发人员自测接口入口。
由于大部分接口是需要登录鉴权才能通过的,此时在swagger提供一个通用的全局的token传输header参数,先调用登录接口,获取到登录token,用swagger自测时后续的接口再传该token参数,来通过服务端鉴权显得尤为必要。
如下图所示,所有接口列表中新增header参数Authorization,非必传。
以下内容由ChatGPT自动生成
在 Swagger2 中,globalOperationParameters 可以用于在全局范围内设置操作参数。这意味着,可以将某些参数应用于所有的 API 操作中,而不必在每个操作中都重复定义它们。
以下是一个示例代码,在 Swagger2 中使用 globalOperationParameters:
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.schema.ModelRef;
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 {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.globalOperationParameters(
Arrays.asList(
new ParameterBuilder()
.name("Authorization")
.description("JWT bearer token")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false)
.build(),
new ParameterBuilder()
.name("X-Custom-Header")
.description("Custom header")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false)
.build()
)
)
.select()
.build();
}
}
在此示例中,我们使用 globalOperationParameters() 方法来定义两个 header 参数 “Authorization” 和 “X-Custom-Header”。这些参数将被应用于所有的 API 操作中。
请注意,globalOperationParameters 方法需要一个参数列表,并接受一个 ParameterBuilder 对象作为其元素。在该示例中,我们创建了两个 ParameterBuilder 对象,分别用于定义 “Authorization” 和 “X-Custom-Header” 参数。在每个对象中,我们指定了参数的名称、描述、数据类型、参数位置和是否必须。
最后,我们将这两个对象添加到 globalOperationParameters 方法的参数列表中。
如果在某些特定 API 操作中需要自定义参数,则可以在操作方法上使用 @ApiImplicitParam 或 @ApiParam 注解。