Skip to content

Adding support for request bodies and nested parameters for PUT and POST method request bodies. #124

Closed
wants to merge 8 commits into from
@vky
vky commented Sep 18, 2013

Ref: #3, #9, #51, #66

This patch adds support for documenting parameters of a request body. As
values are filled into the content parameters, the method's text area is
filled in with what the request body should be. The text area is what
will be submitted as the request body, and can be modified directly if a
user wants to.

@Leonas
Leonas commented Sep 25, 2013

Can you provide an example json file showing how the structure should look for nested parameters?

@vky
vky commented Sep 25, 2013

@Leonas I've added an example json demonstrating usage of nested parameters.

@Leonas
Leonas commented Sep 25, 2013

This works great! Thanks @vkorapaty.

@a-maze-d

This works quite well (thanks for this patch)!

But there are some minor issues that I discovered by playing around with it (might be that I was doing something wrong though):

  • The alignment didn't work properly when using Type boolean (everything was squashed into the first "column". It seems that boolean type is missing in the css/scss (I added it to the css and it seems to have fixed the problem
  • Related to the above: The columns are not quite aligned with the title (probably to use a table as for the request parameters would be the better approach).
  • I had some issues that the boolean didn't work properly until I added explicitly
        "booleanTrueVal": "true",
        "booleanFalseVal": "false"

to the apiconfig.json (even though that should be the default)

And one nice addition would be to not only allow a list of strings or a list of collections, but also a list of enumerates (Even though I specified it, it didn't result in anything :-(

@vky
vky commented Oct 18, 2013

Thanks for the feedback @a-maze-d.

  • Boolean type is there (or at least looks to be) in the scss, it could be that I forgot to regenerate the css file after fixing that. I'll look into what happened there.
  • Alignment is indeed an issue for request parameters. I used nested lists because those were easier to figure out how to style compared to nested tables. Part of the problem is figuring out how to style nested parameters nicely. (My css skills can use work.)
  • I think that's an iodocs thing in general, I think I came across that problem and used enumerated 'true' and 'false' instead for my use case.

List of enumerates is something I noticed wasn't working after submitting the pull request. I'll see what I can do about making that work soon-ish.

@SarahJaneMorris

Hi Vijay!

This is Sarah-Jane, the Developer Community Manager at Mashery. Can you please send me a quick email to smorris @ mashery (dot) com?

We'd like to send you a thank you gift for all of your awesome contributions to I/O Docs!

Cheers,

SJ

@fpingitore

Hi All,

I´m completely new to I/O Docs and Node.js but I´m putting together a heroku API page. The problem I have is that it is almost ready but for some reason I don´t seem to be able to use either object or collections discuss in this patch. What do I need to do to install the patch on my machine? Do I have to reinstall everything Node.js, npm, redis, iodocs?

Thanks,

vky added some commits Sep 18, 2013
@vky vky Setup 'config.rb' for Compass use. Modifying the Sass file will be ea…
…sier with Compass available.
9bc39a3
@vky vky Updated 'style.scss' to generate the current style.css file correctly. d32a315
@vky vky Adding support for request bodies for PUT and POST methods, and nested
parameters for PUT / POST method request bodies.

Functionality description:
This patch adds support for documenting parameters of a request body. As
values are filled into the content parameters, the method's text area is
filled in with what the request body should be. The text area is what
will be submitted as the request body, and can be modified directly if a
user wants to.

Implementation details:
Content parameters use nested lists instead of tables. It was easier to
figure out how to style nested lists compared to styling nested tables.
Styling was done using Sass and Compass, making use of the updated
style.scss.

In app.js, the 'requestBody' variable has been replaced by the 'content'
variable.
a917d25
@vky vky Adding an example API and updating the README.
Adding content_parameters_example.json to demonstrate how the content
parameters work. A first-pass has been taken at documenting the new
functionality in the README.
d631f4a
@vky vky Recompiled stylesheet and fixed a minor error in the content paramete…
…rs example.
a593a08
@vky
vky commented Nov 1, 2013

@fpingitore If you setup I/O Docs using Git, you should be able to run this git pull https://github.com/vkorapaty/iodocs.git feature/content-parameters from your I/O Docs installation directory to pull these commits into your I/O Docs installation. That's all that should be necessary to get this patch setup. If you have I/O Docs currently running, restarting the process should be all you need to do.

For other watchers, the branch has been rebased onto the current master. There was a small merge conflict with the bookmarks patch, no longer now.

@fpingitore

@vkorapaty I´m getting an error when restarting npm. See below:

/Users/Fernando/API/iodocs/app.js:83
var app = module.exports = express();
^
TypeError: object is not a function
at Object. (/Users/Fernando/API/iodocs/app.js:83:28)
at Module._compile (module.js:449:26)
at Object.Module._extensions..js (module.js:467:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Module.runMain (module.js:492:10)
at process.startup.processNextTick.process._tickCallback (node.js:244:9)

Can you help?

@mansilladev

Looking into a merge on this one, Vijay. The choice to use ul and li instead of tables.. before we dig into a rehaul (of either going ul/li or tr/td, but definitely putting in some CSS class renaming), maybe you can elaborate on the choice? Thanks!

@simonmcmanus

Hi,

I don't really mind if you use li or table, lis look nice at the moment but I can see situations where Lis would be more appropriate.

I would really like the ability to post/put some json in the request body though.

Thanks

@simonmcmanus

sorry tables look nice at the moment

@vky
vky commented Feb 25, 2014

@mansilladev At the time, I couldn't come up with an effective way to handle the indentation of nested tables. Lists have automatic indentation built-in, and I was able to handle the nested parameters case relatively easily with recursive mixins in the jade layout, I went with that.

Sass/CSS for nested tables was something that I wasn't sure how to go about also, while styling of nested lists was easier to figure out. The current styling is basically what was a minimally viable product, and the alignment of nested parameters could use work.

lapastillaroja and others added some commits Mar 3, 2014
@lapastillaroja lapastillaroja Three Legged OAuth 1.0: POST, PUT content was empty. Also fixed apiKe…
…y and apiSecret when empty
4192049
@lapastillaroja lapastillaroja Error when content is empty fixed. 3bb13b5
@vky vky Merge pull request #48 from lapastillaroja/feature/content-parameters
Three Legged OAuth 1.0: POST, PUT does not work. Content is always empty
388223d
@asaf
asaf commented Mar 24, 2014

Hey,
Why this was never merged ?

Thanks.

@paulstatezny

I have a need for this feature as well. Can it be merged?

@paulstatezny paulstatezny added a commit to synapsestudios/cookbook-template that referenced this pull request Mar 31, 2014
@paulstatezny paulstatezny Use iodocs fork with support for JSON request body
Pull exists at mashery/iodocs#124 -- has not yet been merged.
0f139e3
@simonmcmanus

The ability to PUT/POST a JSON body was key to me, in the end I built out my own version of IODocs which support some other nice features. I've made it available on github here:

https://github.com/simonmcmanus/livedocs

It doesn't do everything that IODocs does, it generates a single file that can operate without a server (so no oAuth). It should be pretty generic now.

Pull requests welcomed!

@dougschroeder dougschroeder referenced this pull request Apr 12, 2014
Closed

HTTP POST #133

@vasterdev

@vky Hi Vijay, I am using your mod and specifically the "list" type to send the following JSON in the body of a PUT call: {
"fruits": ["apples", "oranges", "bananas"]}. I would like the values of the array to be pre-populated (using the "Default" key value). Is it possible to do that or "Default" only accepts strings? If that's the case then I believe your mod should be extended to allow that functionality as well so as we don't have to add manually 10 or 20 values in the array. Thanx!!!

@avinagrawal

I am trying to develop a REST API Client using iodocs. I saw your patch to implement the POST and PUT requests and tried implementing them. But, I get an error "Content-Length HTTP header missing, request rejected.". Can you please give me some advice as to how I can resolve this problem. I have implemented it in the same way as you have implemented example.api on the page https://github.com/vky/iodocs

@yiannistsi

Is it possible to have more than one Javascript objects by default inside a Collection Type (array)? i.e.
"collection": [
{
"type": "student",
"name": "John"
},
{
"type": "student",
"name": "Mark"
}
]

@alexadkins

Solved by commit 8ff62fc

@alexadkins alexadkins closed this Jul 28, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.