Regarding GeoServer's Swagger REST API documentation, could you please
not include invalid endpoints in the documentation? From a user's point of view, listing invalid endpoints make the spec needlessly harder to read and to follow, and their presence is less helpful than simply not listing the endpoint at all, which already implicitly means it's not supported.
Best regards,
Rui Maciel
Hi Rui,
the documentation was added at the end of a very busy code sprint a couple of years ago and has not been touched much since.
Feel free to make pull requests to improve it, all the swagger docs are in the version control (really, we need someone to care for it,
the existing devs are already overwhelmed with their current duties).
Cheers
Andrea
Regards, Andrea Aime == GeoServer Professional Services from the experts! Visit http://goo.gl/it488V for more information. == Ing. Andrea Aime @geowolf Technical Lead GeoSolutions S.A.S. Via di Montramito 3/A 55054 Massarosa (LU) phone: +39 0584 962313 fax: +39 0584 1660272 mob: +39 339 8844549 http://www.geo-solutions.it http://twitter.com/geosolutions_it ------------------------------------------------------- Con riferimento alla normativa sul trattamento dei dati personali (Reg. UE 2016/679 - Regolamento generale sulla protezione dei dati “GDPR”), si precisa che ogni circostanza inerente alla presente email (il suo contenuto, gli eventuali allegati, etc.) è un dato la cui conoscenza è riservata al/i solo/i destinatario/i indicati dallo scrivente. Se il messaggio Le è giunto per errore, è tenuta/o a cancellarlo, ogni altra operazione è illecita. Le sarei comunque grato se potesse darmene notizia. This email is intended only for the person or entity to which it is addressed and may contain information that is privileged, confidential or otherwise protected from disclosure. We remind that - as provided by European Regulation 2016/679 “GDPR” - copying, dissemination or use of this e-mail or the information herein by anyone other than the intended recipient is prohibited. If you have received this email by mistake, please notify us immediately by telephone or e-mail.
To follow up to Andrea’s point, here is the location of the docs in GitHub:
https://github.com/geoserver/geoserver/tree/master/doc/en/api/1.0.0
If you locate an entry with an invalid endpoint you should be able to edit the file directly to make the fix (and submit a pull request). For changes that affect only one file they fall under our “small contribution” policy in CONTRIBUTING.md so we can review right away without requiring you sign a contribution agreement.
If we take a look at one file like featuretypes.yml you should be able to replace “restng” with “rest” to fix the example URLs.
–
Jody Garnett
Hi,
First of all, thank you for such a quick reply.
Regarding the Swagger docs, some software stacks enable developers to automatically generate them. This approach eliminates the need to maintain documentation, and even serve the docs through a convenient endpoint that also allows users to test the API.
IIRC with Spring all it takes is adding a swagger generation library such as Springfox[1], add some boilerplate code to the project (mainly to setup the Swagger UI endpoint and integrate security) and decorate controllers with some annotations.
What are your thoughts on adopting such a strategy to automatically generate swagger docs of GeoServer's REST API?
Best regards,
Rui Maciel
[1] https://springfox.github.io/springfox/docs/current/
On 21/05/19 18:11, Andrea Aime wrote:
Hi Rui,
the documentation was added at the end of a very busy code sprint a couple of years ago and has not been touched much since.
Feel free to make pull requests to improve it, all the swagger docs are in the version control (really, we need someone to care for it,
the existing devs are already overwhelmed with their current duties).Cheers
AndreaOn Tue, May 21, 2019 at 6:56 PM Rui Maciel <rui.maciel@anonymised.com <mailto:rui.maciel@anonymised.com>> wrote:
Regarding GeoServer's Swagger REST API documentation, could you please
not include invalid endpoints in the documentation? From a user's
point
of view, listing invalid endpoints make the spec needlessly harder to
read and to follow, and their presence is less helpful than simply not
listing the endpoint at all, which already implicitly means it's not
supported.Best regards,
Rui Maciel_______________________________________________
Geoserver-users mailing listPlease make sure you read the following two resources before posting
to this list:
- Earning your support instead of buying it, but Ian Turton:
http://www.ianturton.com/talks/foss4g.html#/
- The GeoServer user list posting guidelines:
http://geoserver.org/comm/userlist-guidelines.htmlIf you want to request a feature or an improvement, also see this:
https://github.com/geoserver/geoserver/wiki/Successfully-requesting-and-integrating-new-features-and-improvements-in-GeoServerGeoserver-users@lists.sourceforge.net
<mailto:Geoserver-users@lists.sourceforge.net>
https://lists.sourceforge.net/lists/listinfo/geoserver-users--
Regards, Andrea Aime == GeoServer Professional Services from the experts! Visit http://goo.gl/it488V for more information. == Ing. Andrea Aime @geowolf Technical Lead GeoSolutions S.A.S. Via di Montramito 3/A 55054 Massarosa (LU) phone: +39 0584 962313 fax: +39 0584 1660272 mob: +39 339 8844549 http://www.geo-solutions.it http://twitter.com/geosolutions_it ------------------------------------------------------- /Con riferimento alla normativa sul trattamento dei dati personali (Reg. UE 2016/679 - Regolamento generale sulla protezione dei dati “GDPR”), si precisa che ogni circostanza inerente alla presente email (il suo contenuto, gli eventuali allegati, etc.) è un dato la cui conoscenza è riservata al/i solo/i destinatario/i indicati dallo scrivente. Se il messaggio Le è giunto per errore, è tenuta/o a cancellarlo, ogni altra operazione è illecita. Le sarei comunque grato se potesse darmene notizia. This email is intended only for the person or entity to which it is addressed and may contain information that is privileged, confidential or otherwise protected from disclosure. We remind that - as provided by European Regulation 2016/679 “GDPR” - copying, dissemination or use of this e-mail or the information herein by anyone other than the intended recipient is prohibited. If you have received this email by mistake, please notify us immediately by telephone or e-mail./
--
Rui Maciel
Senior Engineer
*Spin.Works*
rui.maciel(at)spinworks.pt
www.spinworks.pt <http://www.spinworks.pt/>
CONFIDENTIALITY NOTICE: This message originates from Spin.Works, S.A.
This message including any attachment hereof is confidential and may be
privileged or otherwise legally protected from disclosure and may only
be read, copied and used by the intended recipient. You must not copy
this email or any attachment or disclose its / their contents to any
other person or entity.
I think there were talks about it during the sprint, but it was discarded for some reason… can’t remember why though.
Maybe Torben (cc’ed) remembers.
Cheers
Andrea
GeoServer Professional Services from the experts! Visit http://goo.gl/it488V for more information. == Ing. Andrea Aime @geowolf Technical Lead GeoSolutions S.A.S. Via di Montramito 3/A 55054 Massarosa (LU) phone: +39 0584 962313 fax: +39 0584 1660272 mob: +39 339 8844549 http://www.geo-solutions.it http://twitter.com/geosolutions_it ------------------------------------------------------- Con riferimento alla normativa sul trattamento dei dati personali (Reg. UE 2016/679 - Regolamento generale sulla protezione dei dati “GDPR”), si precisa che ogni circostanza inerente alla presente email (il suo contenuto, gli eventuali allegati, etc.) è un dato la cui conoscenza è riservata al/i solo/i destinatario/i indicati dallo scrivente. Se il messaggio Le è giunto per errore, è tenuta/o a cancellarlo, ogni altra operazione è illecita. Le sarei comunque grato se potesse darmene notizia. This email is intended only for the person or entity to which it is addressed and may contain information that is privileged, confidential or otherwise protected from disclosure. We remind that - as provided by European Regulation 2016/679 “GDPR” - copying, dissemination or use of this e-mail or the information herein by anyone other than the intended recipient is prohibited. If you have received this email by mistake, please notify us immediately by telephone or e-mail.