Define a swagger / openAPI docu

[Teraskull]

My implementation suggestion is to use Flasgger.

In webserver.py we initialize a Swagger instance from the flask app:

from flasgger import Swagger

Swagger(self.server)

And add a docstring to all API endpoint functions, like the followng example:

"""
Returns a dictionary of logging levels.
---
tags:
    - Settings
responses:
    200:
        description: OK
        schema:
            type: object,
            example:
                {
                    critical: str,
                    debug: str,
                    error: str,
                    info: str,
                    notset: str,
                    warning: str
                }
"""

[TobKra96]

Hi,

I reviewed the new API docu. Nice job 👍 Here are some questions:

• The Login and Logout Mechanism, Effect Settings are not documented. I am sure you are still working on it.
• Maybe we can harmonize the delete and create a device function to use the same input style like the get device. To create the device, we can use "id: str" instead of index. And for delete a dive we can use "id:str" instead of device. https://github.com/TobKra96/music_led_strip_control/blob/bf4ab6069fed536bb41ab5830fc5ce359c2e6b79/server/libs/webserver/blueprints/device_api.py#L66 https://github.com/TobKra96/music_led_strip_control/blob/bf4ab6069fed536bb41ab5830fc5ce359c2e6b79/server/libs/webserver/blueprints/device_api.py#L90
• Maybe we can harmonize the device settings, general settings and effect settings too. I would remove the function to get a single setting from the API. We should get all settings and parse them in the FE. I see you combined both API endpoints into one, but this could be confusing. So only accept: https://github.com/TobKra96/music_led_strip_control/blob/bf4ab6069fed536bb41ab5830fc5ce359c2e6b79/server/libs/webserver/blueprints/device_settings_api.py#L60 And the docu has to be modified too. The key for the output will be this one: https://github.com/TobKra96/music_led_strip_control/blob/bf4ab6069fed536bb41ab5830fc5ce359c2e6b79/server/libs/webserver/blueprints/device_settings_api.py#L68
• For the get output type device settings endpoint, I would do the same like above. Only return the complete settings, not only one. https://github.com/TobKra96/music_led_strip_control/blob/bf4ab6069fed536bb41ab5830fc5ce359c2e6b79/server/libs/webserver/blueprints/device_settings_api.py#L141
• The get active effect endpoint has the "device:str" parameter, which is the device id. I think we should harmonize the device id and effect id over all API endpoints. https://github.com/TobKra96/music_led_strip_control/blob/bf4ab6069fed536bb41ab5830fc5ce359c2e6b79/server/libs/webserver/blueprints/effect_api.py#L31 https://github.com/TobKra96/music_led_strip_control/blob/bf4ab6069fed536bb41ab5830fc5ce359c2e6b79/server/libs/webserver/blueprints/effect_api.py#L76

Have a great day, TobKra

[TobKra96]

Done