Migrate to OpenAPI Specification

[arey]

Migrate from Swagger 2 to OpenAPI Specification https://github.com/OAI/OpenAPI-Specification/ and consider the contract-first approach

[alanktwong]

It seems that this fork is in the neighborhood

https://github.com/gantsign/spring-petclinic-openapi

It has a lot of changes from this repo, not least of which the React.js code is embedded in the client directory, and it has no explicit license attached.

[arey]

Thanks you @alanktwong for the link. @freemanjp has done a great work. We could has him which license he choosed?

[alanktwong]

Do you think a separate repo for openapi makes more sense? If so, I think all it needs is 2 gradle subprojects: specification and implementation.

[freemanjp]

The files in the client directory didn't have license headers when I forked the project from https://github.com/spring-petclinic/spring-petclinic-reactjs (I just checked and the files still don't). There also isn't a LICENSE file in the root of the project. The Java files have an Apache 2 header, I expect the client files should have had the same, but to be safe I didn't add a license header where there wasn't one.

If it were a greenfield project I would have put it under the https://unlicense.org (after all the purpose of these showcases is to provide examples for developers to use), but given I forked an existing project, mostly under Apache 2 license, you can consider my changes under the same Apache 2 license where there's nothing specified to the contrary.

It probably doesn't matter as the client directory is React specific, and this repo is backend only. The React code is also pre-React-hooks so isn't worth copying now.

I'm a big proponent of the contract-first approach, ideally to generate both the server and the client APIs. Though that's a bit easier to do when the client and the server are in the same source repository. I don't recommend having the specification in a separate repo, it creates a lot of versioning pain and doesn't provide any practical benefit. It also means your build won't fail if you unintentionally make a REST API change that produces generated code that isn't backwards compatible with your client/server (this can occur even if the REST API itself is backwards compatible). It's best when REST API changes can be built and merged atomically across specification, server and client (particularly for these sort of web apps).

[arey]

The original Spring Petclinic sample has an Apache 2 licence so we keep it. I don't know if we could convert it to unlicense witout authors aggrement? I've added the missing file.

Like @freemanjp I'm a proponent of the contact-first approach. I propose to keep the specification in the same repo. It's easier to maintain.

[alexandre-touret]

Hello,
Is this issue open for work?

[arey]

Yes @alexandre-touret. Are you interested?

[alexandre-touret]

Yes I am.
If you are agree I can migrate from springfox to springdoc : https://springdoc.org/migrating-from-springfox.html