Review API docs

[leogermani]

Review automatic generated docs for all API endpoints.

Also add additional documentation to the website

[leogermani]

Issues that have documentation on some endpoints:

#63

#69

#62

[mateuswetah]

Regarding the Metadata endpoint, I'm putting some considerations here, that need to be checked:

• It is related to the item_metadata, item and collection repositories, so I wasn't sure if we should merge their scheme into the array. Left it commented for now;
• Lots of boolean attributes here are yes/no strings... shouldn't we explain this on the descriptions?
• Some attributes does not seem to be used so far. Here are some:
  • cardinality: Number of multiples possible metadata;
  • parent attribute, do we actually need it?
  • mask: The mask to be used in the metadata (maybe something that can contribute to maximum value length in metadata #276 and Option to allow only uppercase or lower case on terms creation and simple text values. #302?)
  • default_value: The default value for the metadata (are we using it? At least in the front tend we're not);
  • accept_suggestion: Allow community to suggest different values for the metadata (woha, what? Also, this is an actual boolean, one of the few to not use strings)
• How should I describe the metadatum_type_object inner attributes?

[mateuswetah]

Regarding the Filters List endpoint, this needs to be checked:

• It is related to the metadatum and collection repositories, so I wasn't sure if we should merge their scheme into the array. Left it commented for now;
• Some attributes does not seem to be used so far. Here are some:
  • color: The color of the filter (what?);
  • max_options: The max number of options to be showed in filter sidebar. This is used, but it is extremely confusing why this is not an option.
• How should I describe the filter_type_object inner attributes?

[mateuswetah]

Regarding the Taxonomies List endpoint, this needs to be checked:

• The attribute collections_ids is described as type string when it is actually returning an array.

[mateuswetah]

Regarding the Terms List endpoint, this needs to be checked:

• It is related to the taxonomy repository, so I wasn't sure if we should merge this scheme into the array. Left it commented for now;
• About the properties:
  • There is an id and a term_id, I don't think the difference is clear.
  • user: The creator of the term. I don't think it is being used. (And thats weird, isn't it the same thing as the authorid that exists in the repository?);
  • header_image: is missing. There is the header_image_id only in the schema.

[mateuswetah]

Regarding the Logs List endpoint, this needs to be checked:

• About the properties:
  • user_id: The description is weird (Unique identifier, the same as ID) and thats weird, isn't it the same thing as the authorid that exists in the repository?;
  • action, new_value and old_value are missing description. It would be nice to have a list of possible values here too.

[mateuswetah]

Some things to mention from my latest experiments:

• The permanently param on the DELETE of /terms is doing nothing. I believe is because we currently can't trash terms. Previously, there was a info attribute there, which also wasn't doing anything;
• Lots of params are missing their types, I think we could work on this. Boolean values are specially contradictory, sometimes they are yes/no strings, sometime 1/0 integers...
• I put enums on most of the situation where a list of values was the case, but I couldn't think on how to do it on the metadatumtype, as it also accepts stuff like DECIMAL(10,5)...

[mateuswetah]

One more observation:

• The bg-processes endpoint seems to be the only one showing on the documentation plugin a table with the Route Params, not only the Query Params:
  https://tainacan.org/api-docs/endpoints/tainacan/v2/bg-processes/id/

We could find out how and fix the others, because that feature seems interesting!

[vnmedeiros]

reference issue:
#270