Request regarding GeoServer's Swagger REST API documentation

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

Request regarding GeoServer's Swagger REST API documentation

Rui Maciel
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 list

Please 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.html

If 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-GeoServer


[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users
Reply | Threaded
Open this post in threaded view
|

Re: Request regarding GeoServer's Swagger REST API documentation

geowolf
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


On Tue, May 21, 2019 at 6:56 PM Rui Maciel <[hidden email]> 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 list

Please 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.html

If 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-GeoServer


[hidden email]
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.



_______________________________________________
Geoserver-users mailing list

Please 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.html

If 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-GeoServer


[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users
Reply | Threaded
Open this post in threaded view
|

Re: Request regarding GeoServer's Swagger REST API documentation

jody.garnett
In reply to this post by Rui Maciel
To follow up to Andrea's point, here is the location of the docs in GitHub:


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


On Tue, 21 May 2019 at 09:53, Rui Maciel <[hidden email]> 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 list

Please 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.html

If 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-GeoServer


[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users


_______________________________________________
Geoserver-users mailing list

Please 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.html

If 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-GeoServer


[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users
Reply | Threaded
Open this post in threaded view
|

Re: Request regarding GeoServer's Swagger REST API documentation

Rui Maciel
In reply to this post by geowolf
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
> Andrea
>
>
> On Tue, May 21, 2019 at 6:56 PM Rui Maciel <[hidden email]
> <mailto:[hidden email]>> 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 list
>
>     Please 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.html
>
>     If 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-GeoServer
>
>
>     [hidden email]
>     <mailto:[hidden email]>
>     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.


_______________________________________________
Geoserver-users mailing list

Please 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.html

If 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-GeoServer


[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users
Reply | Threaded
Open this post in threaded view
|

Re: Request regarding GeoServer's Swagger REST API documentation

geowolf
On Wed, May 22, 2019 at 10:40 AM Rui Maciel <[hidden email]> wrote:
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?

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.



_______________________________________________
Geoserver-users mailing list

Please 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.html

If 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-GeoServer


[hidden email]
https://lists.sourceforge.net/lists/listinfo/geoserver-users