[Geoserver-users] How to improve documentation of REST?

GeoServer GeoServer User
1

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-

2

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:jukka.rahkonen@anonymised.com]
Sent: Wednesday, September 10, 2014 6:41 AM
To: 'Geoserver-users@lists.sourceforge.net'
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
Geoserver-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-users

3

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

tagCloud.png

···

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) [[mailto:jukka.rahkonen@anonymised.com](mailto:jukka.rahkonen@anonymised.com)] 
Sent: Wednesday, September 10, 2014 6:41 AM
To: '[Geoserver-users@lists.sourceforge.net](mailto:Geoserver-users@anonymised.comists.sourceforge.net)'
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](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](http://docs.geoserver.org/stable/en/user/rest/index.html) and [http://docs.geoserver.org/stable/en/user/rest/api/index.html#rest-api](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](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](http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk)
_______________________________________________
Geoserver-users mailing list
[Geoserver-users@lists.sourceforge.net](mailto:Geoserver-users@anonymised.comsourceforge.net)
[https://lists.sourceforge.net/lists/listinfo/geoserver-users](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](http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk)
_______________________________________________
Geoserver-users mailing list
[Geoserver-users@lists.sourceforge.net](mailto:Geoserver-users@anonymised.comsourceforge.net)
[https://lists.sourceforge.net/lists/listinfo/geoserver-users](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 : jp@anonymised.com
Web : www.pi-geosolutions.fr

4

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

–Steve

tagCloud.png

···

From: Jean Pommier [mailto:jean.pommier@anonymised.com]
Sent: Friday, September 12, 2014 3:05 AM
To: geoserver-users@lists.sourceforge.net
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][.] service while coveragestores only documents file[.] 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) [[mailto:jukka.rahkonen@anonymised.com](mailto:jukka.rahkonen@anonymised.com.)] 

Sent: Wednesday, September 10, 2014 6:41 AM

To: '[Geoserver-users@lists.sourceforge.net](mailto:Geoserver-users@lists.sourceforge.net)'

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](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](http://docs.geoserver.org/stable/en/user/rest/index.html) and [http://docs.geoserver.org/stable/en/user/rest/api/index.html#rest-api](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](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](http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk)

_______________________________________________

Geoserver-users mailing list

[Geoserver-users@lists.sourceforge.net](mailto:Geoserver-users@lists.sourceforge.net)

[https://lists.sourceforge.net/lists/listinfo/geoserver-users](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](http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk)

_______________________________________________

Geoserver-users mailing list

[Geoserver-users@lists.sourceforge.net](mailto:Geoserver-users@lists.sourceforge.net)

[https://lists.sourceforge.net/lists/listinfo/geoserver-users](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 : jp@anonymised.com
Web : www.pi-geosolutions.fr