Fix Legacy OpenAPI specification generation

[sewnie]

Changes

Using oapi-codegen against the full OpenAPI specification and go-swagger against Legacy APIs, I've found a few specification violations in regards to the Legacy APIs, which I have fixed in this PR:

• Thumbnails Api v1:
  • Multiple paths contain query parameter isCircular, defined as boolean, but is defined with enum string
    values ("true" and "false"), and a default string value.
• Inventory Api v1:
  • /v1/packages/{packageId}/assets incorrectly defines parameter packageId as packageID.
• Thumbnails resizer: parameter filterType defined as a query but is actually part of the path.

However, there are some things that are not fixed in this PR that are in violation of OpenAPI, which I can not fix as I need to know the underlying server implementation or original specification:

• Trades v1:
  • Duplicate paths /v1/trades/{tradeId} or {tradeStatusType}
• LocalizationTables v1:
  • Duplicate paths /v1/localization-table/tables/{tableId} or {assetId}
  • Path /v1/localization-table/tables/{tableId}/entry-count parameter entryFormat has
    default value of type int and not a string.

Additionally, For the separated legacy API specifications (Not part of the OpenAPI spec, but the standalone specifications):

• Matchmaking: Specification defined as Swagger 2.0 and uses OpenAPI 3.0 specific fields
• Presence: Specification is not Swagger 2.0 but OpenAPI 2.0 with missing information.

While out of the scope of the PR, I would like to mention that these provide broken contracts:

• Inventory Api v2:
  • Path /v2/users/{userId}/inventory defines parameter assetType as enum int, but it is actually a named string (pointed out by @juliaoverflow), https://inventory.roblox.com/v2/users/5541653843/inventory/2 compared to https://inventory.roblox.com/v2/users/5541653843/inventory?assetTypes=2 and https://inventory.roblox.com/v2/users/5541653843/inventory?assetTypes=Hat

Model names for Legacy APIs are also inconsistent and a little difficult to name, for example, a model could be named as such:

• Roblox.{API}.Api.[Request|Response].{Model}[Request|Response]Model
• Roblox.{API}.Api.Models.{Model}[Request|Response]
• Roblox.Web.WebAPI.Api{Model}[Request|Response]Model
• Roblox.Web.[Request|Response]s.{Source}.{Model}[Request|Response]

Making the legacy models have naming similar to OpenCloud (eg. CreatorStoreProduct over Roblox.AccountInformation.Api.Models.BirthdateResponse) would be helpful, but not a requirement.

The full OpenAPI specification is unsuitable for the legacy APIs, as each legacy API is it's own service under a specific host, and makes code generation difficult, since it is combined with the OpenCloud API (eg. an OpenCloud API and a Legacy API are both defined as functions with no separation inbetween).

While working on manually implementing these endpoints myself, I noticed that the official server does not gurantee the API contract for certain legacy APIs. Unfortunately, I can not recall which endpoints specifically, and I could be incorrect.

Checks

By submitting your pull request for review, you agree to the following:

• This contribution was created in whole or in part by me, and I have the right to submit it under the terms of this repository's open source licenses.
• I understand and agree that this contribution and a record of it are public, maintained indefinitely, and may be redistributed under the terms of this repository's open source licenses.
• To the best of my knowledge, all proposed changes are accurate.

[github-actions]

Hi @sewnie, thanks so much for helping improve the Roblox creator documentation! Our technical writing team will review your pull request soon. In the meantime, please ensure you've read through the README.md, contribution guidelines, and style recommendations.

[aetter]

Hey @sewnie, this is great stuff, thanks for reporting. We generate these JSON files based on a whole bunch of internal definitions and tooling, so I'm going to close this PR in favor of your forum thread. That said, I think the diff here will be useful, so I've sent it along to the developer, as well. Thanks again!