Add validation on json format in swagger UI for node js

Question

Hi I am using swagger UI for documenting APIs in my node.js application. I successfully configured and it is working fine.

But I right now I am facing one serious problem.

here is my sample swagger code from my controller

exports.people = {
  'spec':
  {
    path : "/people",
    method: "POST",
    summary : "Create new person",
    notes : "Create new person",
    nickname : "people",    
    parameters : [param.form("email", "email", "string", true), 
                  param.form("firstName", "firstName", "string", true),
                  param.form("paylod", "Payload", "string", true),
                  param.form("lastName", "lastName", "string", true)]   
  },
  'action': function(req, res)
  {

        -----code----
  }
}

In this, I have payload parameter which take value in json format as

{"id": <your-ID>,"latd":<latitude- value>","long":<longitude- value>"}

but if I pass invalid json like

 id=abc latd=1234 long=asv

then server is crashing . I have to add validation for this parameter so how can I add validation on this particular parameter.

Answer 1

You can set the type of the "payload" to be a model with the id, latd, and long fields, and that should work.

However, you should keep in mind that in Swagger 2.0 this is not really supported anymore.

API-wise, there's a problem with the design - Since you use form parameters, the content-type has to be multipart/form-data , and that means the form parameters themselves do not have a content-type of their own and should remain representation-agnostic. Saying that the structure of the value is a JSON structure pretty much breaks it (documentation-wise, you have no way of saying that it needs to be structured as a JSON and not XML, for example).

Generally, when you want an operation to consume structured data (normally with POST/PUT methods), you would set the overall payload of the operation as that data. To complete that, you would set the mime type of the request as the mime-type of the structured data. In the example above, the simplest mime-type would be application/json . In Swagger, that translates to the "consumes" property. The parameter type itself translates in Swagger to being a body parameter.

The other parameters would then be converted to query parameters, path parameters or header parameters, where query parameters would be the more obvious choice at most times. Depending on the logic of your operation, it may also make sense to push the additional parameters as part of the payload object itself. That goes into various API design paradigms which seem to be out of scope for this question.

As for the additional question about the parameter being required - then yes, you can set the parameter as a whole as being required. If you change it from string to an actual model, you can set the specific fields of that model as required or not.