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
