Swagger Java常用标题 [英] Swagger Java common header
问题描述
我有一个REST API服务器,用 Jersey2.0
实现,并与 Swagger
集成,以自动化文档和客户端应用。
我们有自己的身份验证标头( X-Auth-Token
),应该按顺序应用于所有请求使用它们(如果凭据正确,则在检索令牌的登录请求旁边)。
现在我需要手动将令牌添加为每个请求的 ApiImplicitParam
注释,以便生成的文档包含它:
@ApiImplicitParams({@ ApiImplicitParam(name = AuthFilter.AUTHORIZATION_PROPERTY,value =授权令牌, required = true,dataType =string,paramType =header)})
我不喜欢我想硬编码UI代码以添加标题本身,因为我认为它违反了 swagger.json
提供的API封装。服务器定义应该提供生成的文档所需的所有详细信息。
有没有办法为 Swagger中的所有请求定义自定义默认注释
?或者使用某种过滤器
来实现它?
A快速查看注释
的Swagger UI页面标题
查看
有关其他详细信息,请参阅查看文档。
只是一个快速提示
在测试宠物商店示例时,请确保您添加的标题与该值的匹配header Access-Control-Allow-Headers
。对于宠物商店示例,允许的标头是 Content-Type
, api_key
和授权
。
因此,如果您尝试在宠物中添加 X-Auth-Token
标题存储示例,您将出现以下错误:
XMLHttpRequest无法加载
http://petstore.swagger。 IO / V2 / PET / findByStatus?状态=活性
。预检响应中Access-Control-Allow-Headers
不允许使用请求标头字段X-Auth-Token
。 / p>
I have a REST API server implemented with Jersey2.0
and integrated with Swagger
to automate docs and client side applications.
We have our own authentication header (X-Auth-Token
) which should be applied to all requests in order to use them (Beside the login request that retrieves the token if credentials are correct).
Right now I need to manually add the the token as ApiImplicitParam
annotation to each of the requests in order for the generated docs to include it:
@ApiImplicitParams({@ApiImplicitParam(name = AuthFilter.AUTHORIZATION_PROPERTY, value = "Authorization token", required = true, dataType = "string", paramType = "header")})
I don't want to hardcode the UI code to add the header itself, as I believe it violated the API encapsulation provided by swagger.json
. The server definition should provide all the details necessary for the generated docs.
Is there a way to define a custom default annotation for all requests in Swagger
? Or alternatively use some kind of Filter
to achieve it?
A quick look at the annotations
The ApiImplicitParam
and ApiImplicitParams
annotations are defined as following:
@Target(value=METHOD)
@Retention(value=RUNTIME)
public @interface ApiImplicitParam
@Target(value=METHOD)
@Retention(value=RUNTIME)
public @interface ApiImplicitParams
Please note the @Target(value=METHOD)
. It means these annotations only can be applied to methods.
For more details, check the documentation.
What Swagger UI can do for you
In Swagger UI version 2.1.4 released on 6th January 2016 (the most recent version when this answer was written), you can have an API key:
Have a look at the index.html
. The default implementation sends the API key as a query parameter:
function addApiKeyAuthorization(){
var key = encodeURIComponent($('#input_apiKey')[0].value);
if(key && key.trim() != "") {
var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("api_key", key, "query");
window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
log("added key " + key);
}
}
But you can change it to send a HTTP header:
function addApiKeyAuthorization(){
var key = encodeURIComponent($('#input_apiKey')[0].value);
if(key && key.trim() != "") {
swaggerUi.api.clientAuthorizations.add("key",
new SwaggerClient.ApiKeyAuthorization("Authorization", key, "header"));
log("added Authorization header " + key);
}
}
Consider, for example, the API key you've entered in the box is credentials
. When sending the request, the credentials
value will be sent in the Authorization
header (or in the header you've defined):
For additional details, have a look the documentation.
Just a quick hint
When testing the pet store example, ensure the header you've added matches with the values of the header Access-Control-Allow-Headers
. For the pet store example, the allowed headers are Content-Type
, api_key
and Authorization
.
Hence, if you try adding the X-Auth-Token
header in pet store example, you'll have the following error:
XMLHttpRequest cannot load
http://petstore.swagger.io/v2/pet/findByStatus?status=active
. Request header fieldX-Auth-Token
is not allowed byAccess-Control-Allow-Headers
in preflight response.
这篇关于Swagger Java常用标题的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!