-
Notifications
You must be signed in to change notification settings - Fork 2.2k
-
Notifications
You must be signed in to change notification settings - Fork 2.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
add support for FORM params #69
Comments
@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'? |
@ayush I believe this support would include the following:
Then on the UI, we would need to turn operations of type FORM into post methods, with content type |
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 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:
Thoughts? |
+1 @facultymatt |
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? |
All, we looked into this more. I believe the correct solution is as follows:
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 |
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 |
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 |
While a solid fix is made, I applied this ugly hack to swagger-ui:
It works for me. I am using manually generated .json files. |
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!
To this:
Otherwise parameters will mess up when there's input with characters such as |
=) thanks, updated on my end. Also hoping to have an stable solution for this. |
Please see #107 (comment) |
need to add in jax-rs, swagger-ui modules
The text was updated successfully, but these errors were encountered: