Improve openapi #243
Improve openapi #243
Conversation
Static views created with `static_from` had no metadata in the OpenAPI representation. This is fixed by subclassing our custom View. There was a circular import problem, which I have fixed by removing the `import builder` from `__init__.py` This wasn't used, and only appeared in `__all__`. It appears that removing the import has changed nothing; `from labthings.views import *` still imports the `builder` module.
get_docstring used to discard all indentation. It now uses `inspect.cleandoc()` to remove spurious indents but preserve intentional ones, which results in more nicely formatted markdown docstrings. I have not changed the default remove_newlines=True but I am quite tempted to do so. I'm not convinced by the current trailing space if remove_newlines is True, but have not changed this behaviour because there's no advantage to doing so...
Previously, GET and POST requests both used the same description, which doesn't make sense when they do different things. I've changed this to use` __doc__` or `description` attributes on the `get` or `post` method if available.
Agreed, this is much nicer
I 100% have no problem with ignoring this. Nobody should be using the descriptions for anything other than human reading so it shouldn't break anything.
I think a separate PR would be better just for the sake of historical record. |
Codecov Report
@@ Coverage Diff @@
## master #243 +/- ##
==========================================
- Coverage 90.54% 90.43% -0.11%
==========================================
Files 40 40
Lines 1745 1746 +1
Branches 277 277
==========================================
- Hits 1580 1579 -1
Misses 110 110
- Partials 55 57 +2
Flags with carried forward coverage won't be shown. Click here to find out more.
Continue to review full report at Codecov.
|
|
I need to remember to tag a new release for this soon |
The OpenAPI docs currently leave quite a lot to be desired in the OpenFlexure Microscope. In particular, using the same "description" for GET and POST methods on an Action is confusing, I think. I've changed the APISpec plugin that extracts descriptions so that it looks on the get and post methods first for a docstring, then falls back to the class.
This enables me to make a much nicer API description. However, it might change descriptions in existing code, if there are docstrings on the methods that are currently being ignored. I think this is likely a minor enough problem that it can be ignored...
I have also made what I think is quite a nice factory function to remove boilerplate code from ActionView definitions, I'm happy to add that here, or submit another PR.