Including API method descriptions from Steamworks Documentation pages

[h1nk]

I recently started writing a Steamworks Web API client for Python that uses the automatically tracked and generated api.json data from this repository to dynamically create Python wrapper functions for the different supported and undocumented web API methods. I've been using the description field of each API method to dynamically create docstrings for each method automatically. This would work great, but sadly almost all of the supported web API methods do not include a description field in /ISteamApps/GetAppList/v2/. Only 5 of the methods from the supported API list endpoint include descriptions at the time of writing:

$ curl -s 'https://api.steampowered.com/ISteamWebAPIUtil/GetSupportedAPIList/v1/' | jq '.apilist.interfaces[].methods[].description | values' | wc -l
5

Most API methods do however include helpful documentation descriptions in the Steamworks Web API documentation pages. For instance the web API method /ISteamApps/GetAppList/v2/ has no description field in the machine readable JSON but has a helpful documentation page description:

Gets the complete list of public apps.

This call has no additional parameters.

This method has previous versions which are no longer officially supported. They will continue to be usable but it's highly recommended that you use the latest version.
Change history:

Version 2 - Removed the redundant "app" field.

Response:

• applist
  • apps - The list containing the applications.
    • appid - uint32 - App ID of this application.
    • name - string - The name of this application.

Doing some quick searching on the Internet I wasn't able to find where the Steamworks Documentation pages actually source the missing API method descriptions from so that they could be easily included in this repository.

I'd be willing to write a pull request for a merge script to replace the current generate_api.php one that would quickly scrape and parse the Steamworks Documentation pages for the missing method descriptions so they could be included. With this data It would even be possible to parse the "Response" section of each API method to generate machine readable data about the structure and fields of each API method response.

Including the missing descriptions would not only be beneficial for people such as myself who are currently using data from this repository for projects, but also for the GitHub Pages site itself, as it would give more insight to what supported API methods do without having to constantly flip back and fourth between the Pages site and the Steamworks Documentation pages.

[xPaw]

I thought about it before, but the docs pages are just random blobs of generated html that are not consistent, so I'm more than certain it would break in a lot of cases.

There are also service apis that have protobufs in the steam client, that could be parsed too.

[h1nk]

I'll definitely look into a way to parse the messy blobs of unstructured HTML at some point when I have time so this can be done. The Steamworks web API could definitely benefit from good 3rd party documentation resources, like this project.

Would you also mind pointing me to the Steam client protobuf definitions that contain method descriptions strings that tie to the web API?

[xPaw]

I did a basic parser, it only found 3 methods that aren't listed anywhere else. Other things already got descriptions from protobufs and stuff.