如何正确地添加一个参数，没有错误的swargger氧化锆学说 [英] How to add correctly a parameter without errors in swagger zircote doctrine

问题描述

我第一次使用swagger，下面的代码会导致不是有效的参数定义错误。

i'm using swagger for the first time and the code below results in an "Not a valid parameter definition" error.

/**
 * @SWG\Post(
 *   path="/pub/user/login",
 *   summary="Login",
 *   tags={"User"},
 *   @SWG\Parameter(
 *         name="phone",
 *         in="formData",
 *         description="The phone from the database",
 *         required=true,
 *         type="string"
 *   ),
 *   @SWG\Parameter(
 *         name="token",
 *         in="formData",
 *         description="The token for this device and phone",
 *         required=true,
 *         type="string"
 *   ),
 *   @SWG\Response(
 *     response=200,
 *     description="JWT token"
 *   ),
 *   @SWG\Response(
 *     response=401,
 *     description="Wrong user credentials"
 *   ),
 *   @SWG\Response(
 *     response="default",
 *     description="an ""unexpected"" error"
 *   )
 * )
 */
$app->post('/pub/user/login', function() use($app) {
    $data = $app->request->post();

    $user = UserService::login($data['phone'], $data['token']);
    if ($user != false) {
        ApiService::success(SecurityService::getToken($user));
    } else {
        ApiService::forbidden('Wrong user credentials');
    }

});

---

我发现是我需要为所有参数创建一个定义（但是如何？）：

"definitions": {
    "ResponseDefinition": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": ""
        }
      }
    }

我可以在氧化锆中使用：

i can do that in zircote using:

/**
 * @SWG\Definition()
 */
class Product {

    /**
     * The product name
     * @var string
     * @SWG\Property()
     */
    public $name;
}

除了我的参数不是属性，它只是一个POST参数静态方法

Except that my parameters aren't properties, it's just a POST parameter inside a static method

如何正确执行？

添加：

我的所有终端的完整json是：

my complete json from all my endpoints is:

{"swagger":"2.0","info":{"title":"Mobuyou API","description":"","termsOfService":"","contact":{"email":"[e-mail]"},"version":"1.0.0"},"host":"api.mobuyou.com\/api\/demo","basePath":"\/","schemes":["https"],"paths":{"\/adm\/posdevice":{"post":{"tags":["posdevice"],"summary":"Create a new point of sale fore a merchent","parameters":[{"name":"title","in":"formData","description":"Point of sale's title","required":true,"schema":{"type":"string"},"type":"string"},{"name":"posId","in":"formData","description":"the merchant's point of sale id you want to create","required":true,"schema":{"type":"string"},"type":"string"}],"responses":{"200":{"description":"true|false"},"400":{"description":"missing parameter"}}}},"\/pub\/posdevice\/login":{"post":{"tags":["posdevice"],"summary":"Login","parameters":[{"name":"posDeviceId","in":"formData","description":"The posDeviceId from the database","required":true,"type":"string"},{"name":"token","in":"formData","description":"The token for this device and phone","required":true,"type":"string"}],"responses":{"200":{"description":"JWT token"},"401":{"description":"Wrong user credentials"},"default":{"description":"an \"unexpected\" error"}}}},"\/pub\/posdevice\/demologin":{"post":{"tags":["posdevice"],"summary":"Login","parameters":[{"name":"id","in":"formData","description":"The posDeviceId","required":true,"type":"string"}],"responses":{"200":{"description":"JWT token"},"401":{"description":"Wrong user credentials"},"default":{"description":"an \"unexpected\" error"}}}},"\/sec\/balance":{"get":{"tags":["Balance"],"summary":"Get the balance for the given user","responses":{"200":{"description":"Balance in cents"},"401":{"description":"Not allowed or wrong token"}}}},"\/adm\/merchant":{"post":{"tags":["merchant"],"summary":"Create a new merchant","parameters":[{"name":"title","in":"formData","description":"Merchants title","required":true,"schema":{"type":"string"},"type":"string"}],"responses":{"200":{"description":"true|false"},"400":{"description":"missing parameter"}}}},"\/pub\/merchantmodel\/factor":{"get":{"tags":["Merchantmodel"],"summary":"Get all the model factors","responses":{"200":{"description":"Array of all the models with factors"}}}},"\/adm\/merchantmodel\/factor":{"post":{"tags":["Merchantmodel"],"summary":"Create a new merchantmodel","parameters":[{"name":"title","in":"formData","description":"Verification code","required":true,"schema":{"type":"string"},"type":"string"},{"name":"androidFactor","in":"formData","description":"Verification code","required":true,"schema":{"type":"string"},"type":"string"},{"name":"iosFactor","in":"formData","description":"Verification code","required":true,"schema":{"type":"string"},"type":"string"}],"responses":{"200":{"description":"true|false"},"400":{"description":"missing parameter"}}}},"\/adm\/pos":{"post":{"tags":["pos"],"summary":"Create a new point of sale fore a merchent","parameters":[{"name":"title","in":"formData","description":"Point of sale's title","required":true,"schema":{"type":"string"},"type":"string"},{"name":"merchantId","in":"formData","description":"the merchant's id you want to create a pos for","required":true,"schema":{"type":"string"},"type":"string"}],"responses":{"200":{"description":"true|false"},"400":{"description":"missing parameter"}}}},"\/pub\/register\/phone":{"post":{"tags":["Register"],"summary":"Sends verification code via SMS to given phone number and register the user","parameters":[{"name":"phone","in":"formData","description":"Phone number","required":true,"schema":{"type":"string"},"type":"string"}],"responses":{"200":{"description":"the logintoken for this device"},"default":{"description":"an \"unexpected\" error"}}}},"\/sec\/register\/code":{"post":{"tags":["Register"],"summary":"Verify code from SMS","parameters":[{"name":"phone","in":"formData","description":"the phone number you rechieved the code on by sms","required":true,"schema":{"type":"string"},"type":"string"},{"name":"verificationCode","in":"formData","description":"Verification code","required":true,"schema":{"type":"string"},"type":"string"}],"responses":{"200":{"description":"true"},"401":{"description":"Not a valid verificationCode phone combination or the code is expired, this happens when the session is removed or you tried more than 5 times"},"default":{"description":"an \"unexpected\" error"}}}},"\/sec\/transaction":{"get":{"tags":["Transaction"],"summary":"Get all my transaction","responses":{"200":{"description":"Array of transactions"},"default":{"description":"an \"unexpected\" error"}}},"post":{"tags":["Transaction"],"summary":"Make a transaction to a consumer or a merchant","parameters":[{"name":"consumerId","in":"formData","description":"User ID of the consumer, consumer or merchant","schema":{"type":"integer"},"type":"integer"},{"name":"posDeviceId","in":"formData","description":"the Id of the merchants point of sale device, if the logged in user is a pos device, you can leave this empty","schema":{"type":"integer"},"type":"integer"},{"name":"senderId","in":"formData","description":"the user who pays","schema":{"type":"integer"},"type":"integer"},{"name":"amount","in":"formData","description":"Amount in cents","required":true,"schema":{"type":"integer"},"type":"integer"}],"responses":{"200":{"description":"New balance in cents"},"400":{"description":"An error with the request parameters"},"401":{"description":"Not allowed"}}}},"\/pub\/user\/login":{"post":{"tags":["User"],"summary":"Login","parameters":[{"name":"phone","in":"formData","description":"The phone from the database","required":true,"type":"string"},{"name":"token","in":"formData","description":"The token for this device and phone","required":true,"type":"string"}],"responses":{"200":{"description":"JWT token"},"401":{"description":"Wrong user credentials"},"default":{"description":"an \"unexpected\" error"}}}},"\/pub\/user\/demologin":{"post":{"tags":["User"],"summary":"Login","parameters":[{"name":"id","in":"formData","description":"","required":true,"type":"string"}],"responses":{"200":{"description":"JWT token"},"401":{"description":"Wrong user credentials"},"default":{"description":"an \"unexpected\" error"}}}}},"definitions":{},"securityDefinitions":{"Bearer":{"type":"apiKey","name":"Authorization","in":"header"}}}

这是错误：

{
"messages": ["attribute paths.'/adm/merchantmodel/factor'(post).[iosFactor].schema is unexpected", "attribute paths.'/adm/merchantmodel/factor'(post).[androidFactor].schema is unexpected", "attribute paths.'/sec/register/code'(post).[phone].schema is unexpected", "attribute paths.'/pub/register/phone'(post).[phone].schema is unexpected", "attribute paths.'/adm/posdevice'(post).[title].schema is unexpected", "attribute paths.'/sec/register/code'(post).[verificationCode].schema is unexpected", "attribute paths.'/sec/transaction'(post).[amount].schema is unexpected", "attribute paths.'/sec/transaction'(post).[senderId].schema is unexpected", "attribute paths.'/adm/merchantmodel/factor'(post).[title].schema is unexpected", "attribute paths.'/adm/posdevice'(post).[posId].schema is unexpected", "attribute paths.'/adm/merchant'(post).[title].schema is unexpected", "attribute paths.'/sec/transaction'(post).[consumerId].schema is unexpected", "attribute paths.'/sec/transaction'(post).[posDeviceId].schema is unexpected", "attribute paths.'/adm/pos'(post).[title].schema is unexpected", "attribute paths.'/adm/pos'(post).[merchantId].schema is unexpected"],
"schemaValidationMessages": [{
    "level": "error",
    "domain": "validation",
    "keyword": "pattern",
    "message": "ECMA 262 regex \"^[^{}/ :\\\\]+(?::\\d+)?$\" does not match input string \"api.mobuyou.com/api/demo\"",
    "schema": {
        "loadingURI": "#",
        "pointer": "/properties/host"
    },
    "instance": {
        "pointer": "/host"
    }
    }]

}

推荐答案

不正确：

{
  "name": "consumerId",
  "in": "formData",
  "description": "User ID of the consumer, consumer or merchant",
  "schema": {
    "type": "integer"
  },
  "type": "integer"
},

正确：

{
  "name": "consumerId",
  "in": "formData",
  "description": "User ID of the consumer, consumer or merchant",
  "type": "integer"
},

这篇关于如何正确地添加一个参数，没有错误的swargger氧化锆学说的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！