Open kasp1 opened 7 years ago
Thank you very much for the PR, it looks great.
It seems like in the documentation tab there are switches for "Ownership" and "Restrict" options:
I suppose these are corresponding with the ownership
and restrict
properties of an endpoint. These properties are part of the actual setup of the endpoint and are not meant just for documentation and so they are being setup on the "configuration" page:
If I understand things right here, we can omit these two switches in the documentation tab.
Another thing I noticed is that the endpoint parameters are currectly created just in the "configuration" tab, but the response parameters are supposed to be created in the documentation tab as they are purely just informative. Is there any way to add or remove a response parameter besides editing them?
Thanks for clarification.
The ownership
and restrict
options can be omitted.
Currently, only those response parameters are shown, which are present in the endpoint object. To add response
parameters, there can be a form (like the ones for the new params on configurations tab) which can be populated for each response parameter.
That makes me think? why not support response addition/deletion at the configurations tab?
Perhaps because the response has literally nothing to do with the server's functionality unlike the request parameters. It's purely just informative for third parties who would like to use the API (it can be also seen at the GET /apiko/reference
endpoint).
In that case, we can have:
Adding/Deleting response
on the documentation tab doesn't seem quite right unless I am missing some points?
Suggest if there could be other ways to handle?
If the response section was just read-only, there would be no way editing it. The GET /apiko/reference
endpoint is just a generated document (that can be sent to anyone who is not supposed to have access to the Dev UI), it has no editing capabilities.
Since the response object is there purely to document an endpoint's response, it makes sense to me to put it under documentation tab.
Might be useful to ask others for opinions as well.
The DOCS tab in the Endpoint interface should allow documenting the selected endpoint.
The UI holds a version of the server's setup, which is a JSON of endpoints and collections (in the Vuex store). Documenting an endpoint means adding several specific properties to the selected endpoint's object in this JSON.
This is an example of a documented endpoint:
The documentation specific properties are:
comment
property of the endpoint itself, describes the general purpose of the endpoint.comment
property of each request parameter (in theparams
object), describes what value should be supplied to the parameter.response
object is overall just designed to document the endpoint's response unless it's an error. This object contains for each JSON property in the response body:type
- a string saying what type is the value, may be selected from a drop down menu as String or Numberpresent
- a string saying in what conditions is the property present, may be e.g.always
orif anotherPropert == true
we've got no convention for this yet, suggestions welcome.comment
- a comment saying what is the value of the parameter.All the mentioned documentation properties are optional. The UI should provide a way of editing these in the DOCS tab of each endpoint. There's no UX, suggestions are welcome.