Add examples to Swagger for Senses in gloss update

[susanodd]

BRING BACK THE EXAMPLES from the lost Wiki API examples page

This is incorrect and confusing.

This is what should be the right-hand-side of the json data for Senses:

{"en":[["sense 1 keyword1", "sense 1 keyword2"],["sense 2 keyword1"]], "nl":[["sense 1 keyword1"],["sense 2 keyword1", "sense 2 keyword2"]]}

[susanodd]

@vanlummelhuizen the json expression shown above is from @Jetske. It's the help text if there is an error on the Senses input. Observe that it is not a string.

The original API code was originally a copy paste from the normal interface for senses.

[vanlummelhuizen]

Do you mean

Global-signbank/signbank/gloss_update.py

Line 154 in 372ef1b

return {}, "Sense input is not in the expected format. \nTry: '{\"en\":[[\"sense 1 keyword1\", \"sense 1 keyword2\"],[\"sense 2 keyword1\"]], \"nl\":[[\"sense 1 keyword1\"],[\"sense 2 keyword1\", \"sense 2 keyword2\"]]}'"

?

I get that this should be correct and therefore helpful to the user, but unfortunately it isn't. The JSON you mention above is in single quotes in the help string, so it could be interpreted both as a JSON and as string, making it ambiguous indeed.

```python >>> print("Sense input is not in the expected format. \nTry: '{\"en\":[[\"sense 1 keyword1\", \"sense 1 keyword2\"],[\"sense 2 keyword1\"]], \"nl\":[[\"sense 1 keyword1\"],[\"sense 2 keyword1\", \"sense 2 keyword2\"]]}'") Sense input is not in the expected format. Try: '{"en":[["sense 1 keyword1", "sense 1 keyword2"],["sense 2 keyword1"]], "nl":[["sense 1 keyword1"],["sense 2 keyword1", "sense 2 keyword2"]]}' ```

So, there are two solution to this issue and #1460 :

• Relatively quick and easy:
  • Make the value of Senses a string when using the API, as it was intended al along.
  • Correct the (Swagger) documentation to express this.
  • Fix a minor bug (see Problems sending senses to api_update_gloss #1360 (comment))
• More work:
  • Correct the code so that the value of Senses is interpreted a JSON structure. @susanodd has done some work on that in #1461: Rework code to update senses in API #1463, but we need to take some time for reviewing.

[susanodd]

It was always a json structure. The "update" takes a HUGE json structure containing all the gloss fields that are to be updated.

There used to be numerous examples of how to use it. Both input json and output json.

That was in a separate Wiki API examples page. That page disappeared. Now only Swagger is left.
But Swagger does not have sufficient examples of how to use it.

It was never just a string. It was always a json structure.

We used to use JSON.stringify before passing the giant "update dictionary" in the API.

I don't know about Swagger. It's like it has forms internal to it.

[susanodd]

The "relatively easy" does not work. See the log messages in comments. It causes constraint violations. (This has to do with objects inside the query being deleted while they are still being used. I debugged the original code line by line and there kept being errors. Moreover, it only works to delete the Translation objects if their ids are collected, then they are retrieved and deleted. See the pull request code. Otherwise Django just ignores the attempts to delete. Probably because it's inside a relation table between Gloss and Translation.)

I already implemented the "more work" solution.

[susanodd]

The JSON is in a single quotes because that's how you normally write 'def gloss_update(' code examples. So the reader does not think it's English.

[susanodd]

The intention of this issue is to BRING BACK THE EXAMPLES

Not to discuss gloss update.