Oh, Ok. Sorry my english isn't so good and I hadn't understood all.
An OpenAPI 3 version of geoserver REST contracts already exist and is
debugged ?
It's a very good news for me and there's absolutely no need to continue
using Swagger V2 yaml, then : you're right.
But where are these OAS 3 files ? I'd better use them immediately.
Regards,
Marc.
Le mer. 10 févr. 2021 à 15:30, Gabriel Roldan <gabriel.rol...@gmail.com> a
écrit :
>
>
> On Wed, 10 Feb 2021 at 07:57, Marc LE BIHAN <mlebiha...@gmail.com> wrote:
>
>> Hello,
>>
>> Your tool shows the need to have a way to automate installation(s) of
>> Geoserver sometimes. And I have it too.
>> curl statements aren't enough for this task, and OpenAPI is a convenient
>> way to drive its installation. Using a client API to override it like you
>> do and offer additional help is useful (I have to create internally mine
>> too !). But the beginning is that OpenAPI calls have to work, and there's
>> some corrections to do in yaml files provided, for that.
>>
>> Currently, in [GEOS-9886] issue (that I've renamed to focus only on
>> workspaces.yaml content), I've addressed three flaws :
>> - One in the input content sent to postWorkspaces, that doesn't send the
>> JSON the server expects.
>> - Another in the output of geoserver/rest/workspaces (= list all the
>> workspaces) that should expect an array incoming in return of a call,
>> instead of an object.
>> - Another in the output of geoserver/rest/workspaces/{workspaceName} (= a
>> single workspace) that should expect a "workspace:" incoming instead of an
>> anonymous object.
>>
>>
> If you want to fix the swagger 2 files go for it. I was just pointing out
> there're those OAS3 ones with the errors you mention already fixed if you
> want to use them instead (i.e. given swagger 2 is superseded by OAS3).
>
>
>> I still have to test deleteWorkspace method, and then the workspaces.yaml
>> file will be corrected.
>>
>> I came too far with my idea of a V2 rest yaml files describing the
>> Geoserver REST services, using annotations on server classes to generate
>> these yaml files and ensure their accuracy,
>> but the problem is established : if on that first workspaces.yaml file
>> I've found three bugs, the other might have the same amount and, one by
>> one, depending on my needs, I will have to check and correct them.
>>
>> Regards,
>>
>> Marc.
>>
>> Le mer. 10 févr. 2021 à 01:58, Gabriel Roldan <gabriel.rol...@gmail.com>
>> a écrit :
>>
>>> Hey, I just saw this, sorry for being late to the party
>>>
>>> There's a lot going on in this discussion, so I'll try to be succinct.
>>>
>>> First and foremost, I am generating a Java client from the OpenAPI
>>> documents. Not the swagger 2 ones provided as documentation, but OAS3 ones
>>> created using those as reference.
>>>
>>> Here's a project I just made public a couple of days ago:
>>> https://github.com/camptocamp/geoserver-rest-openapi
>>>
>>> At camptocamp we're using it in production for over a year in an
>>> internal project, but now I moved it as a standalone project to be used by
>>> the OSS project geOrchestra.
>>>
>>> It only implements the minimum I needed for that internal project so
>>> far. That is, working with workspaces, datastores, feature types, layers,
>>> and styles. And probably not even all of it.
>>>
>>> Also, it focuses on JSON representation only.
>>>
>>> On the bright side, it's a standalone library, uses the OpenAPI maven
>>> code generator, and runs integration tests against a GeoServer docker
>>> container managed by the maven life cycle.
>>>
>>> CI builds are set up using github workflows:
>>> https://github.com/camptocamp/geoserver-rest-openapi/actions
>>>
>>> ---
>>> <rant>
>>> That said, writing the OAS3 files and the generated client wrapper code
>>> is hard, often having to debug GeoServer itself to figure out what's going
>>> on in the server to be able of mimicking it on the api definition. There
>>> are several inconsistencies, not only in the outdated/incomplete swagger2
>>> files, but in the server itself, most of which I think are due to using
>>> XStream to generate the JSON representations, like a single object instead
>>> of an array when an array is expected but the result contains a single
>>> element, excessive wrapping of objects, and several other annoyances I
>>> didn't care to document properly at the time, but believe me, I thought
>>> having a working set of OAS3 specs would be a nice first step towards
>>> defining a v2 api with clearly defined api contracts and code-generated
>>> server stubs. Achieving that would of course require significant resources
>>> so it most probably will die in the wish-list.
>>>
>>> But by all means, feel free to check whether that project is of use to
>>> you and to contribute to it. Given enough community interest, we could even
>>> manage to land it as part of geoserver's codebase.
>>>
>>> This Andrea's comment is of most interest and I think I know how to
>>> address it
>>>
>>> > Third, if you want to have reliable yamls that you can generate
>>> clients for, make a plan for it, write a GSIP
>>> <https://docs.geoserver.org/stable/en/developer/policies/gsip.html>,
>>> > resource it fully, and then implement it. Do it in a way that the
>>> system is self sustaining (*every deviation *
>>> *> gets a test failure*) and you might not need to be involved long
>>> term all that much (but plan for some).
>>>
>>> Since the OAS3 api object model (catalog info objects, etc) mirrors
>>> GeoServer Catalog object model, I've experience using mapstruct to create
>>> code-generated object model mappers, and to make the code generation fail
>>> if something changes, which is a good way to ensure both stay in sync.
>>> That'd be of special interest in case a v2 api would be defined, but I had
>>> the intention of creating those mappers nonetheless at least for the sake
>>> of keeping the models in sync.
>>>
>>> As a final note, if I had the resources, I'd very much would like to
>>> implement such new api version, but would definitely do so as a
>>> microservice in the context of this project
>>> https://github.com/camptocamp/geoserver-microservices
>>> </rant>
>>>
>>> Hope that helps,
>>>
>>> Gabriel
>>>
>>> On Mon, 8 Feb 2021 at 04:49, Andrea Aime <andrea.a...@geo-solutions.it>
>>> wrote:
>>>
>>>> On Sun, Feb 7, 2021 at 10:00 PM Marc Le Bihan <mlebiha...@gmail.com>
>>>> wrote:
>>>>
>>>>> 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...)
>>>>>
>>>>
>>>> I don't see the need of a v2, you're not changing the existing REST API
>>>> implementation and the resource representations no? Just its description.
>>>> Nobody is using the yamls to generate clients right now, anyways.
>>>>
>>>> Also, in general, versioning will likely not work, the API changes
>>>> little by little as new needs pop up, we'd be at "v200" (exaggerating of
>>>> course) if we considered every
>>>> model change happened so far, and every new resource addition or new
>>>> request parameter.
>>>>
>>>> What we typically try to do, is to preserve backwards compatibility,
>>>> that is, a client written for a previous release should keep on working
>>>> with the
>>>> new one (new fields are optional), new parameters in resource requests
>>>> are optional.
>>>>
>>>> As said in my previous mail, the yamls are just documentation at the
>>>> moment: I don't know why you explain that a client can be generated
>>>> from YAML files if they are correctly set up (we know that very well),
>>>> as I told you already, right now it's not a goal, due to the limited
>>>> staffing of the project.
>>>> The yaml files have been hand written once, and then mostly left there
>>>> to rot.
>>>>
>>>> If you want to join in the effort to make the yaml files maintainable,
>>>> and provide resources for both its initial setup and long term maintenance,
>>>> then we can make
>>>> "yaml as code generation support" a project goal too. Otherwise there
>>>> is nothing to discuss, it's not a matter of "right or wrong",
>>>> it's a matter of having the man hours to do an initial version of it,
>>>> and then look after it in the long term.
>>>> Existing developers are busy up to their eyeballs and more, there is no
>>>> amount of reasoning that will change that.
>>>>
>>>>
>>>>
>>>>> 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 ?
>>>>>
>>>>
>>>> First step, treat it as documentation and simply issue a fix for the
>>>> yaml.
>>>>
>>>> Second step, if you can write a test that generates a client, and can
>>>> use it in an interaction with a GeoServer,
>>>> in a fully automated way, that is also welcomed (you might need to
>>>> setup a GitHub action build too, if the
>>>> test needs a live GeoServer to work against, otherwise no one will run
>>>> those tests).
>>>>
>>>> Third, if you want to have reliable yamls that you can generate clients
>>>> for, make a plan for it, write a GSIP
>>>> <https://docs.geoserver.org/stable/en/developer/policies/gsip.html>,
>>>> resource it fully, and then implement it. Do it in a way that the
>>>> system is self sustaining (every deviation
>>>> gets a test failure) and you might not need to be involved long term
>>>> all that much (but plan for some).
>>>>
>>>>
>>>> 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-devel mailing list
>>>> Geoserver-devel@lists.sourceforge.net
>>>> https://lists.sourceforge.net/lists/listinfo/geoserver-devel
>>>>
>>>
>>>
>>> --
>>> Gabriel Roldán
>>>
>>
>
> --
> Gabriel Roldán
>
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
