2

For instance, if you wanted an endpoint:

POST /products

that could accept multiple "products" to add to a catalog or something, you could create an HTML form that looked like this:

<form method="post" action="/products">

    <input type="text" name="name[]" />
    <input type="text" name="price[]" />

    <input type="text" name="name[]" />
    <input type="text" name="price[]" />

    <input type="text" name="name[]" />
    <input type="text" name="price[]" />

</form>

You could use JS to duplicate the name[] and price[] inputs so you could send X number of items. Then I could access each one like this (in PHP):

foreach($_POST['name'] as $index => $value){
    $name = $value;
    $price = $_POST['price'][$index];

    $this->addProduct($name, $price);
}

That's easy enough, but having my Swagger docs represent this is harder; more specifically having the Swagger UI html page show the user that each Name-Price pair represents one item in the set. The user should be shown a + button to add another "item" to the set then submit all the "products" together at once.

Is there anything built into the Swagger definition that would represent this? I know I can create an array type and it'd work, but it'd make discovery and testing for the users of API a lot harder. I'd also like to avoid using JSON payloads and stick to FormData.

I'm also using Swagger PHP DocBlock representation. In this case I'd do something like this:

 *@SWG\Post(
 *     tags={"Products"},
 *     path="/products",
 *     operationId="addProducts",
 *     consumes={"application/json"},
 *     produces={"application/json"},
 *     @SWG\Response(
 *          response=201,
 *          description="The newly created Products as JSON"
 *     ),
 *     @SWG\Parameter(
 *          description="Name of the Product",
 *          name="name",
 *          type="string",
 *          in="formData",
 *          required=true
 *     ),
 *     @SWG\Parameter(
 *          description="Price of the Product",
 *          name="price",
 *          type="number",
 *          format="int32",
 *          in="formData",
 *          required=true
 *     )
 * )

As you can see, I can specify the Parameters but I just need some extra glue to tell Swagger that those two parameters represent a single item in a dynamically sized array.

Any ideas?

Keith
  • 4,144
  • 7
  • 25
  • 43
  • HTML form POST requests are `application/x-www-form-urlencoded` or `multipart/form-data`, not `application/json`. Do you need to consume form data or JSON? OpenAPI/Swagger 2.0 supports dynamic arrays in JSON but not in form data. – Helen May 11 '17 at 20:49
  • You're right. The "consumes" part of this is incorrect. So it looks like I'll have to move to a JSON payload instead? That's fine if that's the only option. Do you know if I can have swagger UI represent this in the "add-new-item" way I mentioned? – Keith May 11 '17 at 20:51
  • Yes - in Swagger UI v. 2.2.10 with `jsonEditor: true` (but not in 3.0.x). – Helen May 11 '17 at 21:15

0 Answers0