How to document REST API driven by Grails?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

How to document REST API driven by Grails?

marcopas
Hi there,

we are building a nice grails based REST API but are wondering on how
to document it so that consumers can stay up to date with new features
etc.

I have searched the web and have seen Swagger, I/O Docs etc.
I am wondering if there are some Grails users that have some
recommendations on this subject?

/Marco Pas

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

bksaville
I would be very interested in this as well.  Currently we're using a custom solution based on the DTO generator plugin to generate Java files from our groovy domain classes + some custom javadoc parsing to put it on the generated DTOs -> annogen jam to pull javadoc from the generated java classes -> custom gdoc file generator to create pages for the domain classes as needed.

It's complicated and very messy, and I don't really like it all that much.  But it was all in an effort to get javadoc from domain classes into HTML documentation generated by grails doc.
-Brian


On Mon, Mar 11, 2013 at 4:04 PM, Marco Pas <[hidden email]> wrote:
Hi there,

we are building a nice grails based REST API but are wondering on how
to document it so that consumers can stay up to date with new features
etc.

I have searched the web and have seen Swagger, I/O Docs etc.
I am wondering if there are some Grails users that have some
recommendations on this subject?

/Marco Pas

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email



Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

Owen Rubel
RestRPC plugin has the ability to dynamically generate api docs. The view is very basic but gives you a starting point to modify and play with the data being generated.

RestRPC also allows for alot more like erro handling for your api's, api generation from your controllers and multiple get,post,update,delete per class. It also allows you to pass you domain object as a param (obviously for internal purposes) pass domain object as a map, pass a map, pass a list or whatever and can dynamically handle JSON or XML requests.

Owen Rubel
415-971-0976
[hidden email]


On Mon, Mar 11, 2013 at 3:14 PM, Brian Saville <[hidden email]> wrote:
I would be very interested in this as well.  Currently we're using a custom solution based on the DTO generator plugin to generate Java files from our groovy domain classes + some custom javadoc parsing to put it on the generated DTOs -> annogen jam to pull javadoc from the generated java classes -> custom gdoc file generator to create pages for the domain classes as needed.

It's complicated and very messy, and I don't really like it all that much.  But it was all in an effort to get javadoc from domain classes into HTML documentation generated by grails doc.
-Brian


On Mon, Mar 11, 2013 at 4:04 PM, Marco Pas <[hidden email]> wrote:
Hi there,

we are building a nice grails based REST API but are wondering on how
to document it so that consumers can stay up to date with new features
etc.

I have searched the web and have seen Swagger, I/O Docs etc.
I am wondering if there are some Grails users that have some
recommendations on this subject?

/Marco Pas

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email




Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

Geoff Hopson
This works very well for me - annotation based as opposed to dynamic...





On 3 October 2013 23:35, Owen Rubel <[hidden email]> wrote:
RestRPC plugin has the ability to dynamically generate api docs. The view is very basic but gives you a starting point to modify and play with the data being generated.

RestRPC also allows for alot more like erro handling for your api's, api generation from your controllers and multiple get,post,update,delete per class. It also allows you to pass you domain object as a param (obviously for internal purposes) pass domain object as a map, pass a map, pass a list or whatever and can dynamically handle JSON or XML requests.

Owen Rubel
415-971-0976
[hidden email]


On Mon, Mar 11, 2013 at 3:14 PM, Brian Saville <[hidden email]> wrote:
I would be very interested in this as well.  Currently we're using a custom solution based on the DTO generator plugin to generate Java files from our groovy domain classes + some custom javadoc parsing to put it on the generated DTOs -> annogen jam to pull javadoc from the generated java classes -> custom gdoc file generator to create pages for the domain classes as needed.

It's complicated and very messy, and I don't really like it all that much.  But it was all in an effort to get javadoc from domain classes into HTML documentation generated by grails doc.
-Brian


On Mon, Mar 11, 2013 at 4:04 PM, Marco Pas <[hidden email]> wrote:
Hi there,

we are building a nice grails based REST API but are wondering on how
to document it so that consumers can stay up to date with new features
etc.

I have searched the web and have seen Swagger, I/O Docs etc.
I am wondering if there are some Grails users that have some
recommendations on this subject?

/Marco Pas

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email





Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

Owen Rubel
Thats kind of what it was based on but RestRPC is an all in one; api, api-docs, error handler, etc. It's like Spring Security for the API

Owen Rubel
415-971-0976
[hidden email]


On Fri, Oct 4, 2013 at 9:51 AM, Geoff Hopson <[hidden email]> wrote:
This works very well for me - annotation based as opposed to dynamic...





On 3 October 2013 23:35, Owen Rubel <[hidden email]> wrote:
RestRPC plugin has the ability to dynamically generate api docs. The view is very basic but gives you a starting point to modify and play with the data being generated.

RestRPC also allows for alot more like erro handling for your api's, api generation from your controllers and multiple get,post,update,delete per class. It also allows you to pass you domain object as a param (obviously for internal purposes) pass domain object as a map, pass a map, pass a list or whatever and can dynamically handle JSON or XML requests.

Owen Rubel
<a href="tel:415-971-0976" value="+14159710976" target="_blank">415-971-0976
[hidden email]


On Mon, Mar 11, 2013 at 3:14 PM, Brian Saville <[hidden email]> wrote:
I would be very interested in this as well.  Currently we're using a custom solution based on the DTO generator plugin to generate Java files from our groovy domain classes + some custom javadoc parsing to put it on the generated DTOs -> annogen jam to pull javadoc from the generated java classes -> custom gdoc file generator to create pages for the domain classes as needed.

It's complicated and very messy, and I don't really like it all that much.  But it was all in an effort to get javadoc from domain classes into HTML documentation generated by grails doc.
-Brian


On Mon, Mar 11, 2013 at 4:04 PM, Marco Pas <[hidden email]> wrote:
Hi there,

we are building a nice grails based REST API but are wondering on how
to document it so that consumers can stay up to date with new features
etc.

I have searched the web and have seen Swagger, I/O Docs etc.
I am wondering if there are some Grails users that have some
recommendations on this subject?

/Marco Pas

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email






Reply | Threaded
Open this post in threaded view
|

RE: How to document REST API driven by Grails?

Michael Rice
New plugin: https://github.com/nerdErg/swagger4jaxrs

I have back ported this to work on Grails 2.1.1 and jaxrs 0.6 works like a champ. I highly recommend this if you are using jaxrs.

-mike


From: Owen Rubel [[hidden email]]
Sent: Wednesday, October 09, 2013 12:09 AM
To: [hidden email]
Subject: Re: [grails-user] How to document REST API driven by Grails?

Thats kind of what it was based on but RestRPC is an all in one; api, api-docs, error handler, etc. It's like Spring Security for the API

Owen Rubel
415-971-0976
[hidden email]


On Fri, Oct 4, 2013 at 9:51 AM, Geoff Hopson <[hidden email]> wrote:
This works very well for me - annotation based as opposed to dynamic...





On 3 October 2013 23:35, Owen Rubel <[hidden email]> wrote:
RestRPC plugin has the ability to dynamically generate api docs. The view is very basic but gives you a starting point to modify and play with the data being generated.

RestRPC also allows for alot more like erro handling for your api's, api generation from your controllers and multiple get,post,update,delete per class. It also allows you to pass you domain object as a param (obviously for internal purposes) pass domain object as a map, pass a map, pass a list or whatever and can dynamically handle JSON or XML requests.

Owen Rubel
<a href="tel:415-971-0976" value="&#43;14159710976" target="_blank">415-971-0976
[hidden email]


On Mon, Mar 11, 2013 at 3:14 PM, Brian Saville <[hidden email]> wrote:
I would be very interested in this as well.  Currently we're using a custom solution based on the DTO generator plugin to generate Java files from our groovy domain classes + some custom javadoc parsing to put it on the generated DTOs -> annogen jam to pull javadoc from the generated java classes -> custom gdoc file generator to create pages for the domain classes as needed.

It's complicated and very messy, and I don't really like it all that much.  But it was all in an effort to get javadoc from domain classes into HTML documentation generated by grails doc.
-Brian


On Mon, Mar 11, 2013 at 4:04 PM, Marco Pas <[hidden email]> wrote:
Hi there,

we are building a nice grails based REST API but are wondering on how
to document it so that consumers can stay up to date with new features
etc.

I have searched the web and have seen Swagger, I/O Docs etc.
I am wondering if there are some Grails users that have some
recommendations on this subject?

/Marco Pas

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email






Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

Owen Rubel
how did you lock down the sandbox? Swagger was one of the reasons why I imported dynamically generated api-docs into RestRPC but the Jax-RS doesn't integrate with Grails and Swagger sandbox isnt locked down with Oauth/SAML/OpenID or anything like that so anyone can access it. 

This was why I avoided it and just created a custom api-docs that people can customize.

Owen Rubel
415-971-0976
[hidden email]


On Tue, Oct 8, 2013 at 10:33 PM, Michael Rice <[hidden email]> wrote:
New plugin: https://github.com/nerdErg/swagger4jaxrs

I have back ported this to work on Grails 2.1.1 and jaxrs 0.6 works like a champ. I highly recommend this if you are using jaxrs.

-mike


From: Owen Rubel [[hidden email]]
Sent: Wednesday, October 09, 2013 12:09 AM
To: [hidden email]
Subject: Re: [grails-user] How to document REST API driven by Grails?

Thats kind of what it was based on but RestRPC is an all in one; api, api-docs, error handler, etc. It's like Spring Security for the API

Owen Rubel
<a href="tel:415-971-0976" value="+14159710976" target="_blank">415-971-0976
[hidden email]


On Fri, Oct 4, 2013 at 9:51 AM, Geoff Hopson <[hidden email]> wrote:
This works very well for me - annotation based as opposed to dynamic...





On 3 October 2013 23:35, Owen Rubel <[hidden email]> wrote:
RestRPC plugin has the ability to dynamically generate api docs. The view is very basic but gives you a starting point to modify and play with the data being generated.

RestRPC also allows for alot more like erro handling for your api's, api generation from your controllers and multiple get,post,update,delete per class. It also allows you to pass you domain object as a param (obviously for internal purposes) pass domain object as a map, pass a map, pass a list or whatever and can dynamically handle JSON or XML requests.

Owen Rubel
<a href="tel:415-971-0976" value="+14159710976" target="_blank">415-971-0976
[hidden email]


On Mon, Mar 11, 2013 at 3:14 PM, Brian Saville <[hidden email]> wrote:
I would be very interested in this as well.  Currently we're using a custom solution based on the DTO generator plugin to generate Java files from our groovy domain classes + some custom javadoc parsing to put it on the generated DTOs -> annogen jam to pull javadoc from the generated java classes -> custom gdoc file generator to create pages for the domain classes as needed.

It's complicated and very messy, and I don't really like it all that much.  But it was all in an effort to get javadoc from domain classes into HTML documentation generated by grails doc.
-Brian


On Mon, Mar 11, 2013 at 4:04 PM, Marco Pas <[hidden email]> wrote:
Hi there,

we are building a nice grails based REST API but are wondering on how
to document it so that consumers can stay up to date with new features
etc.

I have searched the web and have seen Swagger, I/O Docs etc.
I am wondering if there are some Grails users that have some
recommendations on this subject?

/Marco Pas

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email







Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

loic911
In reply to this post by marcopas
Hi,

I'm a little bit late  but I've just released RestApiDoc plugin for Grails. Its based on jsondoc lib.
The doc is here: http://loic911.github.io/restapidoc/


Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

Graeme Rocher-2
Looks fantastic, great job!

On Fri, Apr 11, 2014 at 8:49 AM, loic911 <[hidden email]> wrote:

> Hi,
>
> I'm a little bit late  but I've just released RestApiDoc plugin for Grails.
> Its based on jsondoc lib.
> The doc is here: http://loic911.github.io/restapidoc/
>
>
>
>
>
>
> --
> View this message in context: http://grails.1312388.n4.nabble.com/How-to-document-REST-API-driven-by-Grails-tp4642342p4655932.html
> Sent from the Grails - user mailing list archive at Nabble.com.
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>



--
Graeme Rocher
Grails Project Lead
SpringSource

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

sergiomichels
Looks really cool!!

--
Sérgio Michels


On Fri, Apr 11, 2014 at 4:04 AM, Graeme Rocher <[hidden email]> wrote:
Looks fantastic, great job!

On Fri, Apr 11, 2014 at 8:49 AM, loic911 <[hidden email]> wrote:
> Hi,
>
> I'm a little bit late  but I've just released RestApiDoc plugin for Grails.
> Its based on jsondoc lib.
> The doc is here: http://loic911.github.io/restapidoc/
>
>
>
>
>
>
> --
> View this message in context: http://grails.1312388.n4.nabble.com/How-to-document-REST-API-driven-by-Grails-tp4642342p4655932.html
> Sent from the Grails - user mailing list archive at Nabble.com.
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>



--
Graeme Rocher
Grails Project Lead
SpringSource

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email



Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

Owen Rubel
In reply to this post by Graeme Rocher-2
how does this work with Roles? Say for instance I have the api limited by roles or limited to show a reduced dataset per role? how does this adjust?

Owen Rubel
415-971-0976
[hidden email]


On Fri, Apr 11, 2014 at 12:04 AM, Graeme Rocher <[hidden email]> wrote:
Looks fantastic, great job!

On Fri, Apr 11, 2014 at 8:49 AM, loic911 <[hidden email]> wrote:
> Hi,
>
> I'm a little bit late  but I've just released RestApiDoc plugin for Grails.
> Its based on jsondoc lib.
> The doc is here: http://loic911.github.io/restapidoc/
>
>
>
>
>
>
> --
> View this message in context: http://grails.1312388.n4.nabble.com/How-to-document-REST-API-driven-by-Grails-tp4642342p4655932.html
> Sent from the Grails - user mailing list archive at Nabble.com.
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>



--
Graeme Rocher
Grails Project Lead
SpringSource

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email



Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

d.tamm
In reply to this post by loic911
Wow this looks really nice! Will try it next Week :-) one question: is it possible to disable the playground? My customers should only see the documentaion stuff and should not play around :-) hehe

Dominik
Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

loic911
"Looks fantastic, great job!
Looks really cool!!"
Thanks!

"how does this work with Roles? Say for instance I have the api limited by roles or limited to show a reduced dataset per role? how does this adjust?"
Not yet supported. A great idea for a next version.

"one question: is it possible to disable the playground? My customers should only see the documentaion stuff and should not play around :-) hehe"
You may override the grails-app/views/restApiDoc/index.gsp from RestApiDoc and delete the playgroud code (or simply hide the playground element). But its not yet possible to simply disable the playground with a simple line in config.groovy .
Reply | Threaded
Open this post in threaded view
|

Re: How to document REST API driven by Grails?

Owen Rubel
So if this isn't dealing with roles/privileges, integrating this means that your apidocs will be exposing the api config and if you are sending different data or don't want to expose data, this won't matter as it will still show everything, correct?

I mean dont get me wrong, this looks beautiful and this is some GREAT work. But while obfuscation isnt security, sometimes placing a fresh cooked pie in front of a closed window where the hungry can still see it makes for a HORRIBLE temptation. :)

Owen Rubel
415-971-0976
[hidden email]


On Mon, Apr 14, 2014 at 9:18 AM, loic911 <[hidden email]> wrote:

> "Looks fantastic, great job!
> Looks really cool!!"

Thanks!


> "how does this work with Roles? Say for instance I have the api limited by
> roles or limited to show a reduced dataset per role? how does this
> adjust?"

Not yet supported. A great idea for a next version.


> "one question: is it possible to disable the playground? My customers
> should only see the documentaion stuff and should not play around :-)
> hehe"

You may override the grails-app/views/restApiDoc/index.gsp from RestApiDoc
and delete the playgroud code (or simply hide the playground element). But
its not yet possible to simply disable the playground with a simple line in
config.groovy .



--
View this message in context: http://grails.1312388.n4.nabble.com/How-to-document-REST-API-driven-by-Grails-tp4642342p4656008.html
Sent from the Grails - user mailing list archive at Nabble.com.

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email