search

CATH-SWISSMODEL / cath-swissmodel-api

CATH / SWISS-MODEL API: ELIXIR Implementation Study (2018)
3 stars 3 forks source link

move over to OpenAPI v3 #4

Open sillitoe opened 6 years ago

sillitoe commented 6 years ago

current doc is OpenAPI v2, but v3 was released a while ago

sillitoe commented 6 years ago

Ah - so the issue is that there is not yet a JSON schema for v3.0 - see:

https://github.com/OAI/OpenAPI-Specification/issues/1032

For OpenAPI v2.0, the Perl libraries (and possibly other libraries) use this schema to validate the specification document. Without the equivalent document for v3.0, there is no current way of validating this in Perl short of writing my own validation library (which is not going to happen).

gtauriello commented 6 years ago

To be honest, I do not understand the discussion there. It seems very much related to one specific way of validating OpenAPI documents and with lots of arguing about why this or the other type of validation is useful/useless. At the same time, it seems that the swagger editor (https://editor.swagger.io/) happily validates both 2.0 and 3.0.x APIs (and actually complains about two semantic errors for the current API file here).

So in terms of validation, it seems like we could just switch to a different validator and include it in the CI here. At least for validation, that shouldn't be a problem since it's language agnostic. For other tool support which is not language agnostic: is there any problem in support for the new API version?

sillitoe commented 6 years ago

Yes - switching to a different validator shouldn't be a problem.

The libraries that I've been using to support OpenAPI (that do stuff like validating input/output parameters) rely on this schema being present as part of the validation process. Other languages/libraries apparently use their own bespoke validation code rather than rely on this schema. Since the schema hasn't been released for v3.0, if I want to use the libraries I've used previously to implement the client/server then I would need to stick to v2.0 specification.

Looking on the positive side, this could present one more reason for me to learn how to implement this API in Python (though I haven't checked which Python libraries / tools support v3.0 either).

sillitoe commented 6 years ago

Actually I've had a look around for v3.0 support in Python - specifically the libraries involved in simplifying the backend server from the specification document (rather than validating the specification document / creating client code). I'm less familiar in this world so I may have missed something - but it looks like a lot of Python tools / libraries are still waiting for work to be done before v3.0 is ready for production.

Since this is a short project - I think it makes sense to work with tools and libraries that are well tried and tests (both Perl and Python). I would vote for us sticking with the v2.0 specification unless someone has a really good argument against.

Thoughts @gtauriello ?

gtauriello commented 6 years ago

Andrew seems to prefer the newer-is-better approach, but also he doesn't use many tools usually. For now we don't have much experience on the OpenAPI formats, so it's hard to make informed comments. I guess you can continue with your preferred version for now and we can always migrate later. Andrew will be able to give more comments once he gains more knowledge on the topic.

sillitoe commented 6 years ago

Yup, agreed.

Let's use v2.0 to get a working prototype together. There are tools to help migrating from v2.0 to v3.0 so it should be fine if we decide to go that way in the future.

awaterho commented 6 years ago

sorry to be late in here, but it still seems wrong to start a new project on an old version. Juergen Haas who works on Elixir will find out if there is a preferred version to use right now.

sillitoe commented 6 years ago

No problem. Would be good to get thoughts from people who are familiar with the best tools/libraries available in other languages.

awaterho commented 6 years ago

Juergen asked the developers of OpenEBench, an elixir project. They are using version 3 of OpenAPI.

sillitoe commented 6 years ago

Might be worth asking what language / libraries / tools are they using to implement their backend servers with OpenAPI v3.0?

Definitely makes sense to use v3.0 if practical. My concern is that this is a short project and that increases all the risks involved using unfamiliar libraries / dependencies. Would be good to have a clear, well tested route from development to deployment.

I know that I can write and deploy an OpenAPI v2.0 server quickly. It's a pain that this tool-chain can't yet support v3.0, however it looks like it's not the only one - e.g connexion in Python also has an open ticket related to this. Looks like openapi-core might be more promising, but it looks like this offers pretty low-level support - ie may require some work to plug this into existing frameworks.

In terms of making sure we get a working system up and running in 6 months time - it might make sense for me to use v2.0 and the tools I know well to pull a quick prototype together at this end. I don't think this should affect any decisions you make at your end. You guys can start using the v3.0 specification from the start. I'll move over to v3.0 and Python if there's time - that way I would be able to use any best practices that you guys have figured out along the way.

dtkav commented 6 years ago

Hey there - I got a ping because I'm the developer working on OpenAPI 3.0 support in connexion. I thought I'd mention a few libraries that could help you. As you say, you can easily convert from 2->3. https://github.com/p1c2u/openapi-spec-validator (python validator for both v2 and v3) https://github.com/dtkav/swagger2openapi (forked because https://github.com/Mermade/oas-kit is now a monorepo) Good luck!