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

Closed
wants to merge 8 commits into
from

Conversation

Projects
None yet
@vky
Contributor

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

This comment has been minimized.

Show comment
Hide comment
@Leonas

Leonas Sep 25, 2013

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

Leonas commented Sep 25, 2013

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

@vky

This comment has been minimized.

Show comment
Hide comment
@vky

vky Sep 25, 2013

Contributor

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

Contributor

vky commented Sep 25, 2013

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

@Leonas

This comment has been minimized.

Show comment
Hide comment
@Leonas

Leonas Sep 25, 2013

This works great! Thanks @vkorapaty.

Leonas commented Sep 25, 2013

This works great! Thanks @vkorapaty.

@a-maze-d

This comment has been minimized.

Show comment
Hide comment
@a-maze-d

a-maze-d Oct 14, 2013

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 :-(

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

This comment has been minimized.

Show comment
Hide comment
@vky

vky Oct 18, 2013

Contributor

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.

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@SarahJaneMorris

SarahJaneMorris Oct 18, 2013

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

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

This comment has been minimized.

Show comment
Hide comment
@fpingitore

fpingitore Nov 1, 2013

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,

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,

Vijay Korapaty added some commits Sep 18, 2013

Vijay Korapaty
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.
Vijay Korapaty
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.
@vky

This comment has been minimized.

Show comment
Hide comment
@vky

vky Nov 1, 2013

Contributor

@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.

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@fpingitore

fpingitore Nov 2, 2013

@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?

@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

This comment has been minimized.

Show comment
Hide comment
@mansilladev

mansilladev Feb 25, 2014

Contributor

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!

Contributor

mansilladev commented Feb 25, 2014

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

This comment has been minimized.

Show comment
Hide comment
@simonmcmanus

simonmcmanus Feb 25, 2014

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

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

This comment has been minimized.

Show comment
Hide comment
@simonmcmanus

simonmcmanus Feb 25, 2014

sorry tables look nice at the moment

sorry tables look nice at the moment

@vky

This comment has been minimized.

Show comment
Hide comment
@vky

vky Feb 25, 2014

Contributor

@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.

Contributor

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.

@asaf

This comment has been minimized.

Show comment
Hide comment
@asaf

asaf Mar 24, 2014

Hey,
Why this was never merged ?

Thanks.

asaf commented Mar 24, 2014

Hey,
Why this was never merged ?

Thanks.

@paulstatezny

This comment has been minimized.

Show comment
Hide comment
@paulstatezny

paulstatezny Mar 31, 2014

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

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

paulstatezny added a commit to synapsestudios/cookbook-template that referenced this pull request Mar 31, 2014

@simonmcmanus

This comment has been minimized.

Show comment
Hide comment
@simonmcmanus

simonmcmanus Apr 7, 2014

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!

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

This comment has been minimized.

Show comment
Hide comment
@vasterdev

vasterdev May 28, 2014

@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!!!

@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

This comment has been minimized.

Show comment
Hide comment
@avinagrawal

avinagrawal Jun 11, 2014

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

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

This comment has been minimized.

Show comment
Hide comment
@yiannistsi

yiannistsi Jun 26, 2014

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"
}
]

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

This comment has been minimized.

Show comment
Hide comment
@alexadkins

alexadkins Jul 28, 2014

Contributor

Solved by commit 8ff62fc

Contributor

alexadkins commented Jul 28, 2014

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