What's the correct/swagger way to document the request body of a POST method that posts a complex object?

[mikemil]

We are using Swagger but writing the JSON manually (for now - will get automated later). We have some resources that use POST and the post body is a complex object representation in either XML or JSON.

I have tried the following - but haven't really seen any good examples. I have the paramType of body and the dataType as Customer. Is this how you intended this?

The demo project only shows GET requests and really doesn't include a good set of sample coverage of the different parameter types, etc.

partial snippet:
{
"path": "/v1/customers",
"operations": [
{
"method": "POST",
"summary": "Creates a new customer",
"notes": "Creates a new customer using the given customer object.",
"responseClass": "Customer",
"nickname": "",
"produces": [
"application/json",
"application/xml"
],
"parameters": [
{
"name": "body",
"description": "Customer object",
"required": true,
"allowMultiple": false,
"dataType": "Customer",
"paramType": "body"
}
],
"errorResponses": [
{
"code": 400,
"message": "Bad Request. Customer was not created."
}
]
}
]
}

[fehguy]

in the sample here:

http://petstore.swagger.wordnik.com

read the api description--if you enter special-key in the api key area, you'll get options to do post, put, patch, delete. This also includes the option for how you accept XML or JSON via consumes.

[mikemil]

Awesome response time - thanks. Looks like I have it correct - mostly. Next question is how to control the 'parameter type content' dropdown. Looks like by default you get the application/json but our api supports the body as either json or xml - so I need to get 'application/xml' added to the dropdown?

Thanks for the help!

[fehguy]

Yes, just put something like this:

"consumes" : [
  "application/json",
  "application/xml"
]

[mikemil]

I added the below but still only seeing application/json in the dropdown? Is this the correct placement?

"parameters": [
{
"name": "body",
"description": "Customer object",
"required": true,
"allowMultiple": false,
"dataType": "Customer",
"paramType": "body",
"consumes" : [
"application/json",
"application/xml"
]
}

[fehguy]

almost. The spec says that consumes, produces belong to the operation, not the parameters. So for petstore:

"operations": [
  {
    "method": "POST",
    "summary": "Add a new pet to the store",
    "notes": "",
    "type": "void",
    "nickname": "addPet",
    "consumes": [
      "application/json",
      "application/xml"
    ],
    "parameters": [
      {
        "name": "body",
        "description": "Pet object that needs to be added to the store",
        "required": true,
        "type": "Pet",
        "paramType": "body"
      }
    ],
    "responseMessages": [
      {
        "code": 405,
        "message": "Invalid input"
      }
    ]
  }

[mikemil]

Awesome, will move that block out and that should do it!

Sent from my iPhone

On Dec 3, 2013, at 5:38 PM, "Tony Tam" notifications@github.com wrote:

almost. The spec says that consumes, produces belong to the operation, not the parameters. So for petstore:

"operations": [
{
"method": "POST",
"summary": "Add a new pet to the store",
"notes": "",
"type": "void",
"nickname": "addPet",
"consumes": [
"application/json",
"application/xml"
],
"parameters": [
{
"name": "body",
"description": "Pet object that needs to be added to the store",
"required": true,
"type": "Pet",
"paramType": "body"
}
],
"responseMessages": [
{
"code": 405,
"message": "Invalid input"
}
]
}
—
Reply to this email directly or view it on GitHub.

[mikemil]

Perfect - thanks for all the help - love the tool.

Can't wait to get the code base automated so I can stop hand-typing the json. :-)

[fehguy]

what language/server framework do you use?

[mikemil]

We are running in Java, using JBoss 4.2.3 with RestEasy 2.3.5.

[fehguy]

You can build the server from your json files. See here for an example, it should do everything you need. Some tweaking will be needed to use resteasy, but that should be easy:

https://github.com/wordnik/swagger-codegen#to-build-a-server-stub

[fehguy]

Hi @mikemil I'm going to close this, I'm assuming you got going with things. One other thing to add, there is now a YML to Swagger converter here:

https://github.com/wordnik/swagger-codegen/wiki/Creating-Swagger-JSON-from-YAML-files

[fehguy]

Swagger is geared towards REST, not RPC, so you can do it but it may be difficult