ewels
OpenAPI/Swagger API Document
Something it will be useful to do down the track is add a Swagger API documentation: https://swagger.io/specification/. This would integrated nicely with the REST API introduced in #87, and could be implemented using https://github.com/rantav/flask-restful-swagger.
This isn't particularly high priority, but it would give us all the advantages of Swagger, including:
- Client code generation (e.g. we could use https://github.com/swagger-api/swagger-js to provide a client JavaScript API for the front end)
- Automated documentation of the API
- Swagger UI for API exploration: https://swagger.io/tools/swagger-ui/
Why not ditch Flask and go full ASGI with automatic swagger/OpenAPI? I've been using fastapi with huge success, and @tiangolo is a huge help when encountering issues.
This would of course require some rewrite of the code, but it's called "fast"-api for a reason ;)
Cheers M
I can think of a few reasons why not. The primary reason is time. By sticking with the current setup I can make incremental changes to MegaQC, such as my REST API, and trend chart rewrite so that I can get the features I need in before the end of the year. Rewriting everything as an API + React frontend would probably be what I would do if I were starting from scratch, but there isn't a full time developer on this project at the moment. A change like this would involve basically rewriting the entire codebase, minus a few things like the models that could maybe stay.
In addition, I don't think we would gain all that much. The MegaQC codebase is, for the most part, pretty solid. I'm happy with the model layer, the overall layout of the site, and the UI. I have advocated for changing the API format and some parts of the frontend, but everything else would be a waste to rewrite.
Specifically in relation to OpenAPI, I'm also not sure that adding flask-restful-swagger annotations will add all that much work, especially when you compare it to a rewrite.
Sure, you're welcome to. Ideally look for a solution that can automatically generate the schema from the existing REST API in the application, rather than writing it by hand.