在 Swagger / SwaggerUI 中显示所需角色

Question

我们在 Jersey 应用程序中使用 @RolesAllowed 注释来限制用户访问 API 的某些部分。我们如何在 SwaggerUI 中显示这些信息？

到目前为止，我已经使用 @ApiOperation 注释了方法以显示输入/输出参数并尝试使用 @Authorization/@AuthorizationScope 但我只设法为我们不使用的 oauth2 显示它。最接近这种情况的是 ApiKeyAuthDefinition，但它不会显示在 UI 中。

Answer 1

我不熟悉您用来生成 Swagger 的框架，但在我使用的工具中，您必须在文档中的 "securityDefinitions" root node 中指定它，然后为使用它的每个方法引用该定义。

来自我的 Swagger 2.0 JSON 的片段：

"securityDefinitions":{  
      "dapiOAuth2":{  
         "type":"oauth2",
         "description":"OAuth2 security protocol used by this API.  Only one of the scopes that are listed for an endpoint are required to make the request.",
         "flow":"application",
         "authorizationUrl":"https://login.roguecommerce.com/Login",
         "tokenUrl":"https://login.roguecommerce.com/sso/oAuth2/token",
         "scopes":{  
            "RegisteredUser":"Assigned to users of an application if they are registered.",
            "Admin":"Assigned to the users of an application if they are an administrator. This role can only be granted by an existing administrator"
         }
      }
   }

这是您在路径中引用此 securityDefinition 的方式：

"paths":{  
      "/v1/apis":{  
         "post":{  
            "tags":[  
               "Apis"
            ],
            "operationId":"Apis_CreateApiFromSwagger",
            "consumes":[  
               "application/json",
               "text/json",
               "application/xml",
               "text/xml",
               "application/x-www-form-urlencoded"
            ],
            "produces":[  
               "application/json",
               "text/json",
               "application/xml",
               "text/xml"
            ],
            "parameters":[  
               {  
                  "name":"api",
                  "in":"body",
                  "required":true,
                  "schema":{  
                     "$ref":"#/definitions/DynamicApis.Services.Rest.Entities.Api"
                  }
               },
               {  
                  "name":"authorization",
                  "in":"header",
                  "required":true,
                  "type":"string"
               }
            ],
            "responses":{  
               "200":{  
                  "description":"OK",
                  "schema":{  
                     "$ref":"#/definitions/DynamicApis.Services.Rest.Entities.ApiBase"
                  }
               }
            },
            "deprecated":false,
            "security":[  
               {  
                  "dapiOAuth2":[  
                     "admin"
                  ]
               }
            ]
         }
      }
   }

希望这会有所帮助。