How to improve documentation of REST?

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

How to improve documentation of REST?

Rahkonen Jukka (Tike)
Hi,

REST is probably the most common topic on this list. This search finds 5208 mails:
http://sourceforge.net/p/geoserver/mailman/search/?q=REST

I interpret that REST interests users but it is difficult to use and documents that we have do not cover enough use cases. We have documentation in  http://docs.geoserver.org/stable/en/user/rest/index.html and
http://docs.geoserver.org/stable/en/user/rest/api/index.html#rest-api and usage examples in
http://docs.geoserver.org/stable/en/user/rest/examples/index.html#rest-examples

Documentation is not bad but obviously it should be made better. Any suggestions about how to improve it? I believe that is should be something community driven or community assisted because developers are busy with other things and getting funding for improving documentation is just a dream.

-Jukka Rahkonen-

------------------------------------------------------------------------------
Want excitement?
Manually upgrade your production database.
When you want reliability, choose Perforce
Perforce version control. Predictably reliable.
http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk
_______________________________________________
Geoserver-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users
Reply | Threaded
Open this post in threaded view
|

Re: How to improve documentation of REST?

sbrooke
I've had some success with documenting the "representation" classes with Javadoc and then using a tool that understands Spring MVC annotations to generate HTML documentation from the code, that way the REST API docs stay in sync with the code.  The onus though is on the developer working on that portion of the REST API to ensure that good documentation is written up in the Javadoc.

I have done this successfully with RESTdoclet.

This way you get full coverage of all the REST API resources available; what operations are allowed for those resources, the query parameters, and request body parameters all generated from the code (Spring MVC annotations) and Javadoc.

There are several other tools that do this.  Then leave it up to the community to add REST API usage examples as they discover more use cases for how they use it.

My two cents,
--Steve

-----Original Message-----
From: Rahkonen Jukka (Tike) [mailto:[hidden email]]
Sent: Wednesday, September 10, 2014 6:41 AM
To: '[hidden email]'
Subject: [Geoserver-users] How to improve documentation of REST?

Hi,

REST is probably the most common topic on this list. This search finds 5208 mails:
http://sourceforge.net/p/geoserver/mailman/search/?q=REST

I interpret that REST interests users but it is difficult to use and documents that we have do not cover enough use cases. We have documentation in  http://docs.geoserver.org/stable/en/user/rest/index.html and http://docs.geoserver.org/stable/en/user/rest/api/index.html#rest-api and usage examples in http://docs.geoserver.org/stable/en/user/rest/examples/index.html#rest-examples

Documentation is not bad but obviously it should be made better. Any suggestions about how to improve it? I believe that is should be something community driven or community assisted because developers are busy with other things and getting funding for improving documentation is just a dream.

-Jukka Rahkonen-

------------------------------------------------------------------------------
Want excitement?
Manually upgrade your production database.
When you want reliability, choose Perforce Perforce version control. Predictably reliable.
http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk
_______________________________________________
Geoserver-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users

------------------------------------------------------------------------------
Want excitement?
Manually upgrade your production database.
When you want reliability, choose Perforce
Perforce version control. Predictably reliable.
http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk
_______________________________________________
Geoserver-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users
Reply | Threaded
Open this post in threaded view
|

Re: How to improve documentation of REST?

Jean Pommier - PI geosolutions
Hi Steve,

Maybe I missed something.
Do you mean the doc generated for the REST API here ? http://docs.geoserver.org/2.5.x/en/user/rest/api/index.html
Because I'm still on my imagemosaic thing, and something bothers me : in the REST API, I saw nothing about external.imagemosaic service. Shouldn't it be exposed in the coveragestores section, as it is in the datastore section ? Datastore section documents a [file|url|external][.<extension>] service while coveragestores only documents file[.<extension>] service
But maybe it's just some inline doc missing in the code ?

Jean


Le 10/09/2014 17:36, Stephen Brooke a écrit :
I've had some success with documenting the "representation" classes with Javadoc and then using a tool that understands Spring MVC annotations to generate HTML documentation from the code, that way the REST API docs stay in sync with the code.  The onus though is on the developer working on that portion of the REST API to ensure that good documentation is written up in the Javadoc.

I have done this successfully with RESTdoclet.

This way you get full coverage of all the REST API resources available; what operations are allowed for those resources, the query parameters, and request body parameters all generated from the code (Spring MVC annotations) and Javadoc.

There are several other tools that do this.  Then leave it up to the community to add REST API usage examples as they discover more use cases for how they use it.

My two cents,
--Steve

-----Original Message-----
From: Rahkonen Jukka (Tike) [[hidden email]] 
Sent: Wednesday, September 10, 2014 6:41 AM
To: '[hidden email]'
Subject: [Geoserver-users] How to improve documentation of REST?

Hi,

REST is probably the most common topic on this list. This search finds 5208 mails:
http://sourceforge.net/p/geoserver/mailman/search/?q=REST

I interpret that REST interests users but it is difficult to use and documents that we have do not cover enough use cases. We have documentation in  http://docs.geoserver.org/stable/en/user/rest/index.html and http://docs.geoserver.org/stable/en/user/rest/api/index.html#rest-api and usage examples in http://docs.geoserver.org/stable/en/user/rest/examples/index.html#rest-examples

Documentation is not bad but obviously it should be made better. Any suggestions about how to improve it? I believe that is should be something community driven or community assisted because developers are busy with other things and getting funding for improving documentation is just a dream.

-Jukka Rahkonen-

------------------------------------------------------------------------------
Want excitement?
Manually upgrade your production database.
When you want reliability, choose Perforce Perforce version control. Predictably reliable.
http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk
_______________________________________________
Geoserver-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users

------------------------------------------------------------------------------
Want excitement?
Manually upgrade your production database.
When you want reliability, choose Perforce
Perforce version control. Predictably reliable.
http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk
_______________________________________________
Geoserver-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users


--

Jean Pommier -- pi-Geosolutions

Ingénieur, consultant indépendant

Tél. : (+33) 6 09 23 21 36
E-mail : [hidden email]
Web : www.pi-geosolutions.fr


------------------------------------------------------------------------------
Want excitement?
Manually upgrade your production database.
When you want reliability, choose Perforce
Perforce version control. Predictably reliable.
http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk
_______________________________________________
Geoserver-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users
Reply | Threaded
Open this post in threaded view
|

Re: How to improve documentation of REST?

sbrooke

I’m guessing that the use of “external” is just not documented for coveragestores because it does appear to work for me.

 

--Steve

 

From: Jean Pommier [mailto:[hidden email]]
Sent: Friday, September 12, 2014 3:05 AM
To: [hidden email]
Subject: Re: [Geoserver-users] How to improve documentation of REST?

 

Hi Steve,

Maybe I missed something.
Do you mean the doc generated for the REST API here ? http://docs.geoserver.org/2.5.x/en/user/rest/api/index.html
Because I'm still on my imagemosaic thing, and something bothers me : in the REST API, I saw nothing about external.imagemosaic service. Shouldn't it be exposed in the coveragestores section, as it is in the datastore section ? Datastore section documents a [file|url|external][.<extension>] service while coveragestores only documents file[.<extension>] service
But maybe it's just some inline doc missing in the code ?

Jean

Le 10/09/2014 17:36, Stephen Brooke a écrit :

 
I've had some success with documenting the "representation" classes with Javadoc and then using a tool that understands Spring MVC annotations to generate HTML documentation from the code, that way the REST API docs stay in sync with the code.  The onus though is on the developer working on that portion of the REST API to ensure that good documentation is written up in the Javadoc.
 
I have done this successfully with RESTdoclet.
 
This way you get full coverage of all the REST API resources available; what operations are allowed for those resources, the query parameters, and request body parameters all generated from the code (Spring MVC annotations) and Javadoc.
 
There are several other tools that do this.  Then leave it up to the community to add REST API usage examples as they discover more use cases for how they use it.
 
My two cents,
--Steve
 
-----Original Message-----
From: Rahkonen Jukka (Tike) [[hidden email]] 
Sent: Wednesday, September 10, 2014 6:41 AM
To: '[hidden email]'
Subject: [Geoserver-users] How to improve documentation of REST?
 
Hi,
 
REST is probably the most common topic on this list. This search finds 5208 mails:
http://sourceforge.net/p/geoserver/mailman/search/?q=REST
 
I interpret that REST interests users but it is difficult to use and documents that we have do not cover enough use cases. We have documentation in  http://docs.geoserver.org/stable/en/user/rest/index.html and http://docs.geoserver.org/stable/en/user/rest/api/index.html#rest-api and usage examples in http://docs.geoserver.org/stable/en/user/rest/examples/index.html#rest-examples
 
Documentation is not bad but obviously it should be made better. Any suggestions about how to improve it? I believe that is should be something community driven or community assisted because developers are busy with other things and getting funding for improving documentation is just a dream.
 
-Jukka Rahkonen-
 
------------------------------------------------------------------------------
Want excitement?
Manually upgrade your production database.
When you want reliability, choose Perforce Perforce version control. Predictably reliable.
http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk
_______________________________________________
Geoserver-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users
 
------------------------------------------------------------------------------
Want excitement?
Manually upgrade your production database.
When you want reliability, choose Perforce
Perforce version control. Predictably reliable.
http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk
_______________________________________________
Geoserver-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users
 

 

--

Jean Pommier -- pi-Geosolutions

Ingénieur, consultant indépendant

Tél. : (+33) 6 09 23 21 36
E-mail : [hidden email]
Web : www.pi-geosolutions.fr


------------------------------------------------------------------------------
Want excitement?
Manually upgrade your production database.
When you want reliability, choose Perforce
Perforce version control. Predictably reliable.
http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk
_______________________________________________
Geoserver-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users