Draft: Add sagger specs
This MR will add a static swagger 2.0 file and host it in a endpoint (/docs)
This points were taken from Nils feedback
the return payloads for the post & patch requests for the configurations should include the id the configuration devices & platform devices are from my point of view deprecated - I would not include them in the documenation at all
They still listed by us in the urls so i will keep it till we remove it also there.
all the type names seem to be PascalCase in the swagger docs - in reality we use the snake_case (so not ConfigurationStaticLocationBeginAction
, butconfiguration_static_location_action
)the /configuration/{ConfigurationId}/dynamic-location-begin-action
must be pluralI don't know if we really provide patch * delete requests for /configuration/{ConfigurationId}/dynamic-location-begin-action
- those just don't make sense to me
This comes automaticlly from the lib flask-rest-jsonapi
while for the /configuration/{ConfigurationId}/static-location-begin-actions
(and other actions as well) you already provide the filters that can be included in the query parameters - but there are no attributes in the body payloads yet (neither those that should be send to the server, nor those that will be returned).in the fields[XZY]
there are also the PascalCase names - I'm not sure if that makes sense. I would expect the very same value there as the type in the payload.Pagination: In the swagger there often is a default page size of 10. When I tested it with our current staging server, it returned 30 entries by default (but I'm not sure if there is a change in the code for this MR).
I would like to extract this in a extra Issue.
A lot of the descriptions are in the style of "Retrieve DeviceMountAction from device_mount_action" - those doesn't make a lot of sense to me here.
Edited by Kotyba Alhaj Taha