PHP-Swagger查询参数

时间:2014-11-24 09:57:52

标签: php swagger swagger-ui swagger-php

在我的Zend-Application中我正在为移动应用程序编写一个小API。 为了让移动开发人员轻松使用Swagger。 到目前为止,除了一个GET-Request之外,一切正常。

当我在浏览器中调用/ user / messages / {sessionToken}?numMessages = {numMessages}& pageNr = {pageNr}时,我得到了我想要的结果,但是当我尝试让Swagger执行此请求时,仅sessionToken被传输。我为Swagger尝试了这个注释:

/**
 * @SWG\Api(path="/user/messages/{sessionToken}?numMessages={numMessages}&pageNr={pageNr}",
 *   @SWG\Operation(
 *     method="GET",
 *     summary="Gets messages paged",
 *     notes="",
 *     type="string",
 *     nickname="getUsermessagesPaged",
 *     authorizations={},
 *     @SWG\Parameter(
 *       name="sessionToken",
 *       description="The token from an active user session",
 *       required=true,
 *       type="string",
 *       paramType="path",
 *       allowMultiple=true
 *     ),
 *     @SWG\Parameter(
 *       name="numMessages",
 *       description="number of messages on page (numMessages & pageNr are ignored if not both are set)",
 *       required=true,
 *       type="string",
 *       paramType="query",
 *       allowMultiple=true
 *     ),
 *     @SWG\Parameter(
 *       name="pageNr",
 *       description="pagenumber (numMessages & pageNr are ignored if not both are set)",
 *       required=true,
 *       type="string",
 *       paramType="query",
 *       allowMultiple=true
 *     ),
 *     @SWG\ResponseMessage(code=200, message="json {messages => 'user_messages'}"),
 *     @SWG\ResponseMessage(code=400, message="json with error 'not logged in'")
 *   )
 * )
 */

有人看到我的错误吗?

欢迎任何帮助。

亲切的问候

rholtermann

更新:根据建议,我将两个paramTypes更改为“query”并更改了路径:

@SWG\Api(path="/user/messages/{sessionToken}",

但它不起作用。

eclipse PDT中的xdebug显示:

requestURI => /ias/public/user/messages/{sessionToken}

- queryParams => Zend\\Stdlib\\Parameters
     - *ArrayObject*storage => Array[0]
        -  => <Uninitialized>
招摇的JSON是:

{
    "apiVersion": "1.0.0",
    "swaggerVersion": "1.2",
    "apis": [
        {
            "path": "\/user",
            "description": "Operations about users"
        }
    ],
    "info": {
        "title": "Mobile access api",
        "description": "This is the xxx mobile access api.",
        "termsOfServiceUrl": null,
        "contact": "xxx",
        "license": null,
        "licenseUrl": null,
        "_partialId": null,
        "_partials": [ ],
        "_context": {
            "comment": "\/**\ * @SWG\\Info(\ * title="Mobile access api",\ * description="This is the xxx mobile access api.",\ * contact="xxx",\ * )\ *\/",
            "line": 3
        }
    }
}

这是/ user:

的输出
 {
     "basePath": "http://localhost/ias/public",
     "swaggerVersion": "1.2",
     "apiVersion": "1.0.0",
     "resourcePath": "/user",
     "apis": [
         {
             "path": "/user/balance/{sessionToken}",
             "operations": [
                 {
                     "method": "GET",
                     "summary": "Gets userbalance",
                     "nickname": "getUserdata",
                     "type": "string",
                     "parameters": [
                         {
                             "paramType": "path",
                             "name": "sessionToken",
                             "type": "string",
                             "required": true,
                             "allowMultiple": false,
                             "description": "The token from an active user session"
                         }
                     ],
                     "responseMessages": [
                         {
                             "code": 200,
                             "message": "json {balance => 'user_balance'}"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'not logged in'"
                         }
                     ],
                     "notes": "",
                     "authorizations": {}
                 }
             ]
         },
         {
             "path": "/user/login",
             "operations": [
                 {
                     "method": "POST",
                     "summary": "Logs user into the system",
                     "nickname": "loginUser",
                     "type": "string",
                     "parameters": [
                         {
                             "paramType": "form",
                             "name": "email",
                             "type": "string",
                             "required": true,
                             "allowMultiple": false,
                             "description": "The user email for login"
                         },
                         {
                             "paramType": "form",
                             "name": "password",
                             "type": "string",
                             "required": true,
                             "allowMultiple": false,
                             "description": "The password for login in clear text"
                         }
                     ],
                     "responseMessages": [
                         {
                             "code": 200,
                             "message": "json with session_id, user_id, user_balance"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'no user with given email and password'"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'invalid input'"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'no post request'"
                         }
                     ],
                     "notes": "",
                     "authorizations": {}
                 }
             ]
         },
         {
             "path": "/user/logout",
             "operations": [
                 {
                     "method": "POST",
                     "summary": "Logs user out",
                     "nickname": "logoutUser",
                     "type": "string",
                     "parameters": [
                         {
                             "paramType": "form",
                             "name": "sessionToken",
                             "type": "string",
                             "required": true,
                             "allowMultiple": false,
                             "description": "The token from an active user session"
                         }
                     ],
                     "responseMessages": [
                         {
                             "code": 200,
                             "message": "json {result => 'deleted'}"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'no user_session with given sid'"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'invalid input'"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'no post request'"
                         }
                     ],
                     "notes": "",
                     "authorizations": {}
                 }
             ]
         },
         {
             "path": "/user/messages/{sessionToken}",
             "operations": [
                 {
                     "method": "GET",
                     "summary": "Gets new messages",
                     "nickname": "getUsermessages",
                     "type": "string",
                     "parameters": [
                         {
                             "paramType": "path",
                             "name": "sessionToken",
                             "type": "string",
                             "required": true,
                             "allowMultiple": false,
                             "description": "The token from an active user session"
                         }
                     ],
                     "responseMessages": [
                         {
                             "code": 200,
                             "message": "json {messages => 'user_messages'}"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'not logged in'"
                         }
                     ],
                     "notes": "",
                     "authorizations": {}
                 },
                 {
                     "method": "GET",
                     "summary": "Gets messages paged",
                     "nickname": "getUsermessagesPaged",
                     "type": "string",
                     "parameters": [
                         {
                             "paramType": "path",
                             "name": "sessionToken",
                             "type": "string",
                             "required": true,
                             "description": "The token from an active user session"
                         },
                         {
                             "paramType": "query",
                             "name": "numMessages",
                             "type": "string",
                             "required": true,
                             "description": "number of messages on page (numMessages & pageNr are ignored if not both are set)"
                         },
                         {
                             "paramType": "query",
                             "name": "pageNr",
                             "type": "string",
                             "required": true,
                             "description": "pagenumber (numMessages & pageNr are ignored if not both are set)"
                         }
                     ],
                     "responseMessages": [
                         {
                             "code": 200,
                             "message": "json {messages => 'user_messages'}"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'not logged in'"
                         }
                     ],
                     "notes": "",
                     "authorizations": {}
                 }
             ]
         },
         {
             "path": "/user/userdata",
             "operations": [
                 {
                     "method": "POST",
                     "summary": "Posts userdata",
                     "nickname": "postUserdata",
                     "type": "string",
                     "parameters": [
                         {
                             "paramType": "form",
                             "name": "sessionToken",
                             "type": "string",
                             "required": true,
                             "allowMultiple": false,
                             "description": "The token from an active user session"
                         },
                         {
                             "paramType": "form",
                             "name": "password",
                             "type": "string",
                             "required": false,
                             "allowMultiple": false,
                             "description": "new password"
                         },
                         {
                             "paramType": "form",
                             "name": "address",
                             "type": "string",
                             "required": false,
                             "allowMultiple": false,
                             "description": "new address"
                         },
                         {
                             "paramType": "form",
                             "name": "housenr",
                             "type": "string",
                             "required": false,
                             "allowMultiple": false,
                             "description": "new housenr"
                         },
                         {
                             "paramType": "form",
                             "name": "zip",
                             "type": "string",
                             "required": false,
                             "allowMultiple": false,
                             "description": "new zip"
                         },
                         {
                             "paramType": "form",
                             "name": "city",
                             "type": "string",
                             "required": false,
                             "allowMultiple": false,
                             "description": "new city"
                         },
                         {
                             "paramType": "form",
                             "name": "email",
                             "type": "string",
                             "required": false,
                             "allowMultiple": false,
                             "description": "new email"
                         }
                     ],
                     "responseMessages": [
                         {
                             "code": 200,
                             "message": "json {user => 'userdata'}"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'not logged in'"
                         }
                     ],
                     "notes": "",
                     "authorizations": {}
                 }
             ]
         },
         {
             "path": "/user/userdata/{sessionToken}",
             "operations": [
                 {
                     "method": "GET",
                     "summary": "Gets userdata",
                     "nickname": "getUserdata",
                     "type": "string",
                     "parameters": [
                         {
                             "paramType": "path",
                             "name": "sessionToken",
                             "type": "string",
                             "required": true,
                             "allowMultiple": false,
                             "description": "The token from an active user session"
                         }
                     ],
                     "responseMessages": [
                         {
                             "code": 200,
                             "message": "json {user => 'userdata', user_limit => 'userLimits'}"
                         },
                         {
                             "code": 400,
                             "message": "json with error 'not logged in'"
                         }
                     ],
                     "notes": "",
                     "authorizations": {}
                 }
             ]
         }
     ],
     "produces": [
         "application/json"
     ]
 }

错误似乎是,我的swagger-ui没有发出任何查询参数? 这是一个只有一个query-param的例子,sessionToken: (由FireBug 2.0.6监控)

GET /ias/public/user/balance HTTP/1.1
Host: localhost
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:33.0) Gecko/20100101 Firefox/33.0
Accept: application/json
Accept-Language: de,en-US;q=0.7,en;q=0.3
Accept-Encoding: gzip, deflate
Content-Type: application/json
Referer: http://localhost/ias/swagger/
Cookie: __utma=111872281.581414660.1366700677.1394721873.1394723866.255; uvts=sB5Dda3cZBNdaTk; searchpanel-close=set
Connection: keep-alive

答案是:

HTTP/1.1 400 Bad Request
Date: Tue, 25 Nov 2014 14:58:20 GMT
Server: Apache/2.4.9 (Win32) PHP/5.5.12
X-Powered-By: PHP/5.5.12
Content-Length: 25
Connection: close
Content-Type: application/json; charset=utf-8

答案是正确的,因为没有传输sessionToken。

此请求有效,但并非来自swagger-ui:

GET /ias/public/user/balance?sessionToken=54275cc6358e42c4b1fb1d8daf850b52 HTTP/1.1
Host: localhost
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:33.0) Gecko/20100101 Firefox/33.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: de,en-US;q=0.7,en;q=0.3
Accept-Encoding: gzip, deflate
Cookie: __utma=111872281.581414660.1366700677.1394721873.1394723866.255; uvts=sB5Dda3cZBNdaTk; searchpanel-close=set
Connection: keep-alive

3 个答案:

答案 0 :(得分:1)

将第一行更改为:

* @SWG\Api(path="/user/messages/{sessionToken}",

Swagger不支持查询参数作为路径本身的一部分。它们将被自动添加到请求中(来自UI),因为它们被描述为query类型。

答案 1 :(得分:0)

我认为你错过了

paramType="query",

paramType="path",

我认为这将解决您的问题

答案 2 :(得分:0)

问题解决了,解决方法是更新swagger-ui。

更新后,查询参数已发送到应用程序,一切正常。

感谢所有试图解决我问题的人。

亲切的问候 rholtermann