#1865 Document API
Closed: MIGRATED a year ago by nikromen. Opened 2 years ago by msuchy.

We should document our API. Not just the Python bindings.

This is a good start point. https://stackoverflow.com/questions/36634281/list-of-swagger-ui-alternatives.

I personally like the Swagger most (like this one https://api.studer-innotec.com/swagger/ui/index#!/Installation/Installation_ReadParameter )
But ReDoc or Swagger-UI (the fork) looks good too.


Metadata Update from @praiskup:
- Issue tagged with: API

2 years ago

We should do this, for sure.
Swagger (OpenAPI) seems to be a good choice. I don't have any experience with neither but the usage doesn't seem to be very complicated

https://github.com/flasgger/flasgger#using-dictionaries-as-raw-specs

There is one important thing we IMHO shouldn't overlook. Currently, APIv3 uses our custom forms in forms.py, that are shared with the web UI counterpart of that API action. We IMHO shouldn't get to the point where API defines its own form definitions and the web UI has its own separate form definitions.

We should IMHO migrate both API and web UI to use the same definitions/forms or generate them for one of those from the other.

We IMHO shouldn't get to the point where API defines its own form definitions and the web UI has its own separate form definitions.

The question is whether we can transform the form input into the OpenAPI
input easily. If not, IMVHO we don't have to stick with this dogma. The
current approach is pretty hard to understand, it really caused nightmares
to me.

OpenAPI-like like interface is a good enough reason to start with IMO
api_4, if the api_3 can not stay compatible while moving to OpenAPI.

Metadata Update from @nikromen:
- Issue close_status updated to: MIGRATED
- Issue status updated to: Closed (was: Open)

a year ago

Login to comment on this ticket.

Metadata