查询参数注释在Swagger中以身体参数生成？

Question

我有一个使用Restlet Swagger Extention的雷神API应用程序，通过Swagger2SpecificationRestlet生成Swagger JSON。

// route to generated swagger json
swagger2SpecificationRestlet.attach(router, "/docs");  

我的路线是这样定义的：

router.attach("/path/{pathParam}", MyResource.class);

我已经在本地实施了Swagger-UI，并设置了初始化器URL，以读取/docs的Swagger JSON。在包括所需路径参数输入的所有路由的所有路线上，UI的工作原理，但是查询参数的注释在没有其他定义的字段的情况下呈现为邮局（？）。参数输入：

"parameters": [
    {
        "name": "pathParam",
        "in": "path",
        "required": true,
        "type": "string"
    },
    {
        "in": "body",
        "name": "body",
        "required": false,
        "schema": {
        "type": "string"
    }
],

带注释的我的资源方法：

    @ApiOperation(
        value="test desc",
        httpMethod = "GET", 
        produces = "application/json", 
        notes="testing notes"
    )
    @Get("txt")
    public String represent(
        @ApiParam(name="queryParam", value = "testing desc") 
        @QueryParam("queryParam") String queryParam
        ) throws SQLException { ... }

我如何注释查询参数，以生成正确的JSON配置？

Answer 1

在进一步查看了文档之后，我遇到了这一点：

noreferrer“> https://docs.swagger.io/swagger-core/apidocs/com/wordnik/wordnik/swagger/annotations/apiimpliticparam.html#paramtype

public @interface apiimpliticparam代表一个单个参数
API操作。当Apiparam绑定到JAX-RS参数时，方法
或字段，这使您可以手动定义一个参数
微调的方式。 这是定义参数的唯一方法
使用servlet或其他非JAX-RS环境。

我用apiparam apiimpliticparam ，该有一个字段来声明param类型，并将注释移动上述注释该方法：

    @ApiOperation(
        value="get stuff",
        httpMethod = "GET", 
        produces = "application/json", 
        notes="test notes"
    )
    @Get("txt")
    @ApiImplicitParam(
        name="queryParam", 
        dataType = "String", 
        paramType = "query", 
        value = "testing query param desc", 
        defaultValue = "default val")
    public String represent() throws SQLException {
        return getMethod();
    }

它导致正确生成的JSON：

"parameters": [
    {
        "name": "pathParam",
        "in": "path",
        "required": true,
        "type": "string"
    },
    {
        "name": "queryParam",
        "in": "query",
        "description": "testing query param desc",
        "required": false,
        "type": "string",
        "default": "default val"
    }
]