I have taken a pass over another set of endpoints, this time the /user endpoints. Overall, there were less changes to these endpoints compared to previous groups I have done. Most of the work for this group focused on the /user/notifications endpoint. This is because marshmallow (the python library doing the schema validation for us) doesn’t allow any kind of polymorphism in its schemata, thereby preventing the use of the anyOf part of the OpenAPI spec. So, I had to define a base notification schema and then tried to document the optional fields to indicate what fields would be present for which type of notification.

Here is crust running the updated swagger and here is the codeberg PR. I have included a changelog compared to 1.1 below:

  • GET /user

    • limit input parameter now defaults to 20. Previously default was 50 for posts and 10 for comments.

  • PUT /user/subscribe

    • added subscribed field to response to mirror similar pattern elsewhere, like /user/block

  • PUT /user/save_user_settings

    • Documented some input fields that were previously undocumented in the swagger
    • Documented the response

  • POST /user/set_flair

    • modified so that either omitting the flair_text field or setting it to null will remove existing flair

  • GET /user/notifications

    • status input field options renamed to one of Unread, Read, or All
    • unread field replaces new_notifications in the counts field
    • read field replaces read_notifications in the counts field
    • total field replaces total_notifications in the counts field
    • I had to redefine the schema for the items field because the auto-documenting library we are using doesn’t support the OpenAPI anyOf feature. So, this field is now a list of a generic notification schema. I have documented which types of notifications the optional fields are returned for.
    • username field replaces user since it is just a string rather than a whole schema

  • I added the about_html field to a couple schema (/site and /user/save_user_settings responses both have it) as the html version of a user’s about in case it would be easier for you to use the html version of a user’s bio instead of markdown.