If a good client cannot be generated by Swagger generator tool from a yaml file that has a Swagger yaml format, it means that the content of the yaml file is wrong. It's what I've detected, and you can see it on https://docs.geoserver.org/stable/en/api/#1.0.0/workspaces.yaml <https://docs.geoserver.org/stable/en/api/#1.0.0/workspaces.yaml> swagger UI description for postWorkspaces method information where it says that workspaceBody is about to send a
{
"name" : "string"
}
when you know that the server is waiting for a :
{
"workspace": {
"name": "string"
}
}(see attachment) and this is what I've corrected on a sample file (an attachment of my previous e-mail, I put corrected yaml file in this one too). Nothing else has to be done - yet - than correcting faulty yaml declarations, and this should not be a big problem.
For how to correct REST services in the long term and completely, and ensure their accuracy with server side about what is given as documentation and for generation, I agree with you. It's another work. For that, I think the best thing to do would be to annotate server classes and object to allow Swagger/Open Api to produce their exact declarations of services in a new yaml file. But this new yaml file and Swagger-UI documentation should be in another URL, let say /geoserver/rest/v2/... to ensure that existing code that rely on version 1 of the API can continue to use /geoserver/rest/... without trouble .
(but this is only the beginning of a solution...) But summarizing :I've corrected the faulty yaml file (for postWorkspaces method only, yet) and now it allows client generation by Swagger that works with Geoserver : geoNode project is not needed for calling it.
Workspace workspace = new Workspace();
workspace.setName("ecoemploi");
WorkspaceRequest workspaceRequest = new WorkspaceRequest();
workspaceRequest.setWorkspace(workspace);
WorkspacesApi workspacesApi = new WorkspacesApi(apiClient());
String response = workspacesApi.postWorkspaces(workspaceRequest,
true);
My question is :Do you want this file to be integrated in the restconfig project with a test if I can create one that is convincing, or do you think it's too much, too early, and I better keep these corrected file for myself, for my own use only ?
Regards, Marc. On 07/02/2021 18:48, Andrea Aime wrote:
On Sun, Feb 7, 2021 at 6:10 PM Marc Le Bihan <mlebiha...@gmail.com <mailto:mlebiha...@gmail.com>> wrote:I think no tool or no part of Geoserver use the content of the yaml rest config files at the moment.Correct, they have been hand-written as a documentation effort during the 2017 code sprint <http://geoserver.org/behind%20the%20scenes/2017/01/23/geoserver-code-sprint-2017.html>. Generating a client was not a goal back then, it's still not today (they are not really being maintained all that much).There is also a separate issue that would need to be handled, that is, the REST representation changes as soon as one of the internal config objects (CatalogInfo implementers) changes, which happens every one and then, but without anyone ever caring to update the YAML files. The changes are always made so that new fields are not mandatory, in order to allow backwardscompatibility with the old stored XML files.Nothing in REST needs to be touched, as the representations are build using a reflection like mechanism (XStream in particular), but a client written in a type safe language mighthave issues adapting.As far as I know, core devs are not generating clients, and my colleagues that are using the REST API do so using a hand-written python library, https://github.com/GeoNode/geoserver-restconfig <https://github.com/GeoNode/geoserver-restconfig>I guess these clients are tolerant to representation changing,I believe having YAML files that can be used to generate clients from is a worthy goal, but we need more developers to get involved in the project and take care of that part, either by generating the yamls from code (to keep the aligned at all time), or trying to follow the developmentsas they happen.Aside, it's also a problem we have with the OGC APIs, the yaml service files are pieced together by hand and templated a bit to add a list of valid values, but no attempt is made to check if clients can be generated, and if they would actually work. And again, same deal as above, we need more people, or some sponsorship to figure out a yaml file generation from code, which would make ithappen almost effortlessly. Best regards Andrea== GeoServer Professional Services from the experts! Visit http://goo.gl/it488V <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://www.geo-solutions.it> http://twitter.com/geosolutions_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./
workspaces.yaml
Description: application/yaml
_______________________________________________ Geoserver-devel mailing list Geoserver-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/geoserver-devel
