Typo: API documentation contains wrong key in getScenes response example

[malliaridis]

Description

In https://stream-labs.github.io/streamlabs-obs-api-docs/docs/index.html#response the response example probably holds outdated or just wrong key information. The key for the scene nodes is nodes instead of activeItemIds.

Environment details

Streamlabs OBS Version: 1.1.2 Operating System: Windows API Docs Version: Unknown

Steps to validate the typo

1. Connect to Streamlabs OBS
2. Send following request:

   {
   "jsonrpc": "2.0",
   "id": 1,
   "method": "createScene",
   "params": {
   "resource": "ScenesService",
   "args": [""]
   }
   }

3. See response:

   {
   "id": 1,
   "result": [
      {
           "_type": "HELPER",
           "resourceId": "Scene[\"scene_93c5fbde-7db4-4894-a84a-e6aab8229665\"]",
           "id": "scene_93c5fbde-7db4-4894-a84a-e6aab8229665",
           "name": "Some Scene",
           "nodes": [
              {...},
              {...}
           ]
       },
      {...}
   ],
   "jsonrpc": "2.0"
   }

Further Information

It seems like the content is hardcoded in the documentation and therefore never updated automatically. A couple of improvements could be done or discussed here:

• Include an API version in the documentation It is better traced back that way and this also allows consumers to work towards a specific version and include / exclude support for older / newer versions of the API
• Generate the API from the actual implementation This might be more complicated and time consuming, but would avoid outdated content like the reported one
• Just update the documentation if it is hardcoded The way the documentation is generated is unknown. If it is manually written then a simple update would cost less time and fix the issue (temporarily)

[holiber]

Thanks for reporting that. I agree we need to include an API version in the documentation. However, we didn't introduce any breaking changes since we implemented this API and it always has the same major version, and practically we change only a minor version.

We can not use the SLOBS version number as a version for our API because our changes in SLOBS rarely affect API. So we need to figure out how we should determine the version of API first.

Our documentation is not hardcoded you can generate it from jsdoc with the command yarn typedoc. However, to publish this documentation we should create a PR with generated files for this repo https://github.com/stream-labs/streamlabs-obs-api-docs This documentation published via GitHub pages here https://stream-labs.github.io/streamlabs-obs-api-docs/docs/index.html

I'm going to sync these docs at the end of the week. PRs from the community are appreciated too.

[malliaridis]

I would like to test the yarn typedoc command and check the recent changes made to the api docs, but it seems like the main project makes use of an outdated version of typedoc? Getting the following error with typedoc 0.21.2:

$ yarn typedoc
yarn run v1.22.4
$ typedoc --out docs/dist ./app/services/api/external-api/ --mode modules --theme ./docs/theme --readme ./docs/README.md --ignoreCompilerErrors --excludePrivate --excludeProtected --excludeExternals --hideGenerator
Error: Unknown option: --mode
Error: Unknown option: --ignoreCompilerErrors
Error: Unknown option: --mode
Error: Unknown option: --ignoreCompilerErrors
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

According to the typedoc's changelog 0.20.0 some of the used options were removed. Should that be updated so the docs can be generated with the newer version of typedoc? By only removing the outdated options other errors are thrown.

About the API version, I agree that keeping track of the API version with different version number than SLOBS is better. Providing then changelogs and migrations from one version to another would come in handy for API consumers.

[holiber]

The docs for this API were generated on Typedoc v0.16.11. It's not in project dependencies because we rarely used it and it adds too many redundant dependencies to the project. I created a ticket for updating the Typedoc.