Provide documentation links to original API

[unode]

While searching for what is returned for each endpoint call, I'm finding myself constantly jumping between the driver endpoint docs the source links and https://api.mattermost.com/ often fumbling to find the correct API endpoint.

Would it be possible to generate a link back to the original documentation from every endpoint entry in the endpoint documentation?

[Vaelor]

Sounds like a cool idea and something I would like to see. Not sure yet though how to do that, maybe it would be easier to do if the whole api is generated from the openapi files mattermost uses for their docs.

[unode]

We could maybe start by adding the api URL as a docstring to all existing functions.

E.g. adding GET /users/{user_id} to get_user() makes it then easy to find the corresponding entry in the openAPI JSON file (or using the "find text" browser feature while on the Mattermost API website).

[unode]

Looking at the swagger.json file, it seems doable:

    "/users/{user_id}": {
      "get": {
        "tags": [
          "users"
        ],
        "summary": "Get a user",
        "description": "Get a user a object. Sensitive information will be sanitized out.\n##### Permissions\nRequires an active session but no other permissions.\n",
        "operationId": "GetUser",
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "description": "User GUID. This can also be \"me\" which will point to the current user.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
(...)

/users/{user_id} is the name of the endpoint, operationID seems to translate to the function name. GetUser -> get_user and operationID can also be used to construct the URL to the API Docs: https://api.mattermost.com/#operation/GetUser

[unode]

Hum... seems like not all function names work this way. E.g. set_bot_lhs_icon is operationID: SetBotIconImage.

I see two paths forward:

1. A manually created mapping of function_name -> API - e.g. using the docstring as initially suggested
2. Functions are renamed to follow operationID - This breaks existing API but could be fixed with thin compatibility layer that raises deprecation warnings and a call to the operationID based function names.

Thoughts?