Skip to content

Draft: Add sagger specs

Kotyba Alhaj Taha requested to merge Add_sagger_specs into master

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, but configuration_static_location_action)
  • the /configuration/{ConfigurationId}/dynamic-location-begin-action must be plural
  • I 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

Merge request reports