使用Swagger + Java REST API

Question

如何注释需要用户身份验证的REST API，以使摇动页面正确反映输入？

到目前为止，这是我的Java代码：

@ApiOperation(
        value = "Requires Authentication. Updates a user",
        notes = "Requires Authentication. Updates a user",
        response = BaseResponse.class
)
@Path("/updateUser")
@POST
public BaseResponse updateUser(@Auth UserPrincipal userPrincipal, @ApiParam(value = "user request", required = true) User userRequest) {

但是，它突然显示为：

我需要添加到REST方法中的哪些附加注释？

Answer 1

至少使用支持OpenAPI v2的dropwizard-swagger，在类上使用这些注释：

@SwaggerDefinition(securityDefinition = @SecurityDefinition(
        apiKeyAuthDefinitions = {
                @ApiKeyAuthDefinition(key = "custom",
                        name = "authorization",
                        in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER,
                        description = "Bearer Authentication")}))

并且在方法上，请参考安全性：

@ApiOperation(authorizations = @Authorization("custom"),
            value = "Requires Authentication. Returns dashboard",
            notes = "Requires Authentication. Returns dashboard",
            response = ResultResponse.class
    )
    @Path("/getDashboard")
    @POST
    public ResultResponse getDashboard(@Auth @ApiParam(hidden = true) APIKeyPrincipal apiKeyPrincipal,
                                                 @ApiParam(value = "Calculator Request", required = true) CalculatorRequest req) {

重要的是添加@ApiParam（hidden = true），这样它就不会出现在Swagger UI中。

在Swagger用户界面中，您现在应该会在其中填写详细信息的地方看到一个锁定图标。确保还包含不记名令牌的名称，例如“承载者”。现在，您还应该在API旁边看到一个锁定图标，可以对其进行测试。