在 Java EE / Jersey 中将不记名令牌的字段添加到生成的 Swagger UI
Add field for bearer token to generated Swagger UI in Java EE / Jersey
我有一个 Java EE 8 应用程序,我在其中使用 OpenAPI 注释来定义我的REST 端点 并自动生成 Swagger UI。对于身份验证,我使用 JSON Web 令牌 (JWT).
当我从 Postman 发送请求时一切正常,但是,我不知道如何将不记名令牌的字段添加到我的 Swagger UI。
我正在使用 @SecurityScheme
注释定义我的安全方案:
@SecurityScheme(
securitySchemeName = "JWT",
description = "JWT authentication with bearer token",
type = SecuritySchemeType.HTTP,
scheme = "bearer",
bearerFormat = "Bearer [token]"
)
public class ApplicationConfig extends Application {
}
我尝试将此方案作为 @SecurityRequirement
添加到我的资源的 @OpenAPIDefinition
注释中,并直接添加到我的方法中。
@Path("/items")
@OpenAPIDefinition(
info = @Info(title = "Items resource", version = "v1"),
security = @SecurityRequirement(name = "JWT")
)
@Transactional(value = TxType.REQUIRES_NEW)
@Interceptors({RolesAllowedInterceptor.class})
@SecurityScheme(
securitySchemeName = "JWT",
description = "JWT authentication with bearer token",
type = SecuritySchemeType.HTTP,
scheme = "bearer",
bearerFormat = "Bearer [token]"
)
public class ItemsResource {
(...)
@GET
@Operation(description = "Returns the item list overview")
@APIResponse(responseCode = "200", description = "Valid response")
@APIResponse(responseCode = "401", description = "Authentication required")
@APIResponse(responseCode = "500", description = "Unexpected exception")
@Produces({MediaType.APPLICATION_JSON})
@SecurityRequirement(name ="JWT", scopes = "write: read")
@RolesAllowed({Constants.USER_ROLE_EXPERT})
public Response getItemListOverview() throws TechnicalException {
ItemListOverviewVO itemListOverviewVO = logic.getItemListOverview();
return Response.status(Status.OK).entity(itemListOverviewVO).build();
}
所以我现在在我的 OpenAPI JSON 文件中有 security
信息,但是 UI 中仍然没有 Authorization 参数字段。
我也发现以前在旧的SwaggerAPI里面有一个@ApiImplicitParameter
注解(见),不过好像从OpenAPI.
所以我尝试使用 @HeaderParam
代替(参见 Jersey project Swagger-UI doesn't send @HeaderParam while @PathParam is sent):
public Response getItemListOverview(@HeaderParam("Authorization") String bearerToken) throws TechnicalException {
现在我的 UI 中有一个 授权 字段,但是当我测试端点时,请求没有授权 header。我在浏览器的网络分析中看不到它。
OpenAPI documentation 到目前为止帮助不大。我在这里遗漏了什么吗?
关键是在@Components()
中嵌入@SecurityScheme
注释,并将其作为参数传递给@OpenAPIDefinition
注释:
@OpenAPIDefinition(
info = @Info(title = "My application", version = "1.0.0"),
servers = {@Server(url = "/myapp", description = "localhost") },
security = @SecurityRequirement(name = "JWT"),
components = @Components(securitySchemes = @SecurityScheme(
securitySchemeName = "JWT",
description = "JWT authentication with bearer token",
type = SecuritySchemeType.HTTP,
scheme = "bearer",
bearerFormat = "Bearer [token]"))
)
public class ApplicationConfig extends Application {
}
我有一个 Java EE 8 应用程序,我在其中使用 OpenAPI 注释来定义我的REST 端点 并自动生成 Swagger UI。对于身份验证,我使用 JSON Web 令牌 (JWT).
当我从 Postman 发送请求时一切正常,但是,我不知道如何将不记名令牌的字段添加到我的 Swagger UI。
我正在使用 @SecurityScheme
注释定义我的安全方案:
@SecurityScheme(
securitySchemeName = "JWT",
description = "JWT authentication with bearer token",
type = SecuritySchemeType.HTTP,
scheme = "bearer",
bearerFormat = "Bearer [token]"
)
public class ApplicationConfig extends Application {
}
我尝试将此方案作为 @SecurityRequirement
添加到我的资源的 @OpenAPIDefinition
注释中,并直接添加到我的方法中。
@Path("/items")
@OpenAPIDefinition(
info = @Info(title = "Items resource", version = "v1"),
security = @SecurityRequirement(name = "JWT")
)
@Transactional(value = TxType.REQUIRES_NEW)
@Interceptors({RolesAllowedInterceptor.class})
@SecurityScheme(
securitySchemeName = "JWT",
description = "JWT authentication with bearer token",
type = SecuritySchemeType.HTTP,
scheme = "bearer",
bearerFormat = "Bearer [token]"
)
public class ItemsResource {
(...)
@GET
@Operation(description = "Returns the item list overview")
@APIResponse(responseCode = "200", description = "Valid response")
@APIResponse(responseCode = "401", description = "Authentication required")
@APIResponse(responseCode = "500", description = "Unexpected exception")
@Produces({MediaType.APPLICATION_JSON})
@SecurityRequirement(name ="JWT", scopes = "write: read")
@RolesAllowed({Constants.USER_ROLE_EXPERT})
public Response getItemListOverview() throws TechnicalException {
ItemListOverviewVO itemListOverviewVO = logic.getItemListOverview();
return Response.status(Status.OK).entity(itemListOverviewVO).build();
}
所以我现在在我的 OpenAPI JSON 文件中有 security
信息,但是 UI 中仍然没有 Authorization 参数字段。
我也发现以前在旧的SwaggerAPI里面有一个@ApiImplicitParameter
注解(见
所以我尝试使用 @HeaderParam
代替(参见 Jersey project Swagger-UI doesn't send @HeaderParam while @PathParam is sent):
public Response getItemListOverview(@HeaderParam("Authorization") String bearerToken) throws TechnicalException {
现在我的 UI 中有一个 授权 字段,但是当我测试端点时,请求没有授权 header。我在浏览器的网络分析中看不到它。
OpenAPI documentation 到目前为止帮助不大。我在这里遗漏了什么吗?
关键是在@Components()
中嵌入@SecurityScheme
注释,并将其作为参数传递给@OpenAPIDefinition
注释:
@OpenAPIDefinition(
info = @Info(title = "My application", version = "1.0.0"),
servers = {@Server(url = "/myapp", description = "localhost") },
security = @SecurityRequirement(name = "JWT"),
components = @Components(securitySchemes = @SecurityScheme(
securitySchemeName = "JWT",
description = "JWT authentication with bearer token",
type = SecuritySchemeType.HTTP,
scheme = "bearer",
bearerFormat = "Bearer [token]"))
)
public class ApplicationConfig extends Application {
}