add support for FORM params

[fehguy]

need to add in jax-rs, swagger-ui modules

[ayush]

@fehguy Maybe I'm missing something here but I'm not sure what needs to be done in swagger-core here. Swagger-core simply 'documents' the availability of API interfaces. Whether these API interfaces accepts POST bodies in as a form/url-encoded or in JSON or in XML or plain text is a function of how the controllers were written and whether the stack (jax-rs or play framework) automatically supports one or more of these or not.

From the perspective of swagger project, doesn't this need to be simply a parameter to swagger-ui which allows users of swagger-ui to set the contentType for body params to be anything they want: for example 'application/json' or 'text/plain' or 'application/x-www-form-urlencoded'?

[fehguy]

@ayush I believe this support would include the following:

• telling the api annotation that the input would be from a form post. The class will need the appropriate content-type set in it
• specifying that the API in the swagger json spec would be of type FORM

Then on the UI, we would need to turn operations of type FORM into post methods, with content type x-www-form-urlencoded

[facultymatt]

I second some type of support for forms and posts. Here is an example use case. I have an api that allows users to create new accounts.

The endpoint is POST /users/signup. The API requires 3 parameters: email, name, password and accepts 1 optional parameter location.

Sure, as @ayush points out on the server side I might be accepting xml, json, etc. But on the swagger-ui side I want to have individual fields, that can be marked required, int, string, etc. for users to fill out. I don't want them to have to compose a json object or xml string... only to make a request and then have the server tell them they didn't fill out required fields.

@ayush while you point out that swagger is meant to document API's, its hard to ignore the usefulness of testing GET requests. If the functionality of testing fully RESTful apis was baked in it would be more useful. See http://hurl.it/ for a great example.

With this in mind, I would propose the following:

1. Add to @operation a field that allows users to specify which formats their server accepts. Maybe this is instead a global setting on the swagger-ui side, just as users can set supportedSubmitMethods.
2. Set each parameter as (that would normally be grouping into one REQUEST_BODY or similar) as a type="form" or even type="query"
3. When a method is POST, all params that are now type="path" are sent as fromData. The proper content type is set, ie: x-www-form-urlencoded. In additon, the users specified "auth_token" is automatically added to either header or as additional post parameter.

Thoughts?

[jbeuckm]

+1 @facultymatt

[diaspar]

Hi I am experiencing the same problem. I am documenting an API that has methods that only accept POST params in the form: key=value.

Any development on this? Can someone point out what to modify on swagger.js to accomplish this?

[fehguy]

All, we looked into this more. I believe the correct solution is as follows:

1. The issue is the input format from a x-www-form-encoded is not JSON, whereas the swagger-ui supports only JSON POST input.
2. The server needs to tell the consumer (swagger-ui) that the input type should be x-www-form-encoded rather than json by declaring what input format it expects
3. The swagger specification needs to be amended to support the additional input format declaration (point 2)

That said, version 1.2 of the swagger specification will have this additional input--input format (see https://github.com/wordnik/swagger-core/wiki/Specification-Roadmap) as well as explicitly setting the content type being produced. There is branch of swagger-core here:

https://github.com/wordnik/swagger-core/tree/1.2.0-spec

with a docs folder containing sample specs with the new format. They're not done, but will be shortly. Please keep watching this thread and I'll post back when things are updated. Thanks for the patience on this issue!

[miketzian]

I agree that moving forward using 'Consumes' or something similar should be the way to go.

Today, swagger provides these:

"operations": [
{
    "httpMethod": "POST",
    "parameters": [{
        "paramType": "form",
    }]
}

Which swagger ui could use to infer that it should be submitting a form rather than doing a json post.

Looking at the 1.2.0 spec though, I'm not sure that covers all bases (though i'm sure it's just the sample):

https://github.com/wordnik/swagger-core/blob/1.2.0-spec/docs/specs-1.2/pet.json

Having produces / consumes at the top level is ok, though they should additionally be able to be defined at the method level as well.

Wanted to double check that that's what you're looking to do. Otherwise, it wont cover this off unless all methods have post options.

-Mike

[fehguy]

Hi Mike, yes--the plan is to have each of the fields available at the top-level, and overridable at each method. This will apply to consumes, produces, and protocols as well. The samples will keep getting updated, and turn into a proper doc.

[diaspar]

While a solid fix is made, I applied this ugly hack to swagger-ui:

    bodyParam = null;
    _ref2 = this.model.parameters;
    for (_k = 0, _len2 = _ref2.length; _k < _len2; _k++) {
      param = _ref2[_k];
      if (param.paramType === 'body') {
        bodyParam = map[param.name];
      } else {
        if (_k == 0) {
        bodyParam = '';
        }
        if(typeof map[param.name] === 'undefined'){
           bodyParam += param.name + '=';
        } else {  
           bodyParam += param.name + '=' + map[param.name];
        }

        if (_k < _len2 - 1) {
            bodyParam += '&';
        };
      }
    }
    log("bodyParam = " + bodyParam);
    log(this.model.httpMethod);
    headerParams = null;
    if (this.model.httpMethod === 'post') {
        headerParams = {'Content-Type': 'application/x-www-form-urlencoded'};
    };

It works for me. I am using manually generated .json files.

[CamiloMM]

Hi @diaspar, where did you put that? I'm having to document an API that also uses "form POST" so I don't want to have people format the query string by hand, and would love to have fields for each property too.

I'm also using manually generated .json.

To the developers, this feature is sorely needed! Any news on this issue @fehguy?

Edit: Figured the patch out, thank you very much!
Edit 2: Just one note. Change that line:

           bodyParam += param.name + '=' + map[param.name];

To this:

           bodyParam += param.name + '=' + encodeURIComponent(map[param.name]);

Otherwise parameters will mess up when there's input with characters such as & or = (to name a couple).

[diaspar]

=) thanks, updated on my end. Also hoping to have an stable solution for this.

[fehguy]

Please see #107 (comment)