Improved API docs
This MR aims to produce better HTTP API documentation. In so doing, I've also tried to remove some boilerplate code from the API definition, and put the API definition closer to the Python function implementations to avoid defining arguments in multiple places.
Specifically, I've introduced a new ActionView class factory that creates a custom ActionView subclass to explicitly wrap a function. That means we can use the function's name and docstring in the API description, which removes a lot of boilerplate code. I am not attempting to automatically convert the function's arguments into an API schema; you still need to supply a Marshmallow schema.
I have also added a decorator (currently the class factory is part of said decorator, I intend to split them) so that methods of an extension can be decorated with @extension_action(args) to automatically create an API endpoint for actions.
In due course I should do the same for properties and events...
Things that should happen here before it can be merged:
-
Ensure the OpenAPI documentation that's generated is valid -
Fix the defaultreturn code, errors should be described as5XX -
Add response descriptions for non-JSON endpoints (MJPEG stream, RAM capture) -
Fix static folders for extensions
-
-
Allow GET/POST descriptions to propagate through LabThings -
Document all the actions in the autofocusplugin -
Document lots of actions elsewhere -
Check (manually?) that I've not changed any of the parameters for the actions -
Check that I've not broken anything with the decorators vs ActionView definitions -
Move wrapper/factory classes to LabThings (may be for the future) -
Revert git branch dependency on labthings to a release -
Wait for necessary LabThings changes to be merged and released -
Update dependencies to use newly-released LabThings -
Check one last time and mark as no longer draft :D