Add docs for API v2

[Chew]

This will be a draft for a while, but this PR adds docs for the new JSON:API v2 changes to RAWeb.

This also adds an OpenAPI spec for all of the endpoints.

The sidebar changes allows there to be v1 and v2 docs. Most v2 pages, including the sidebar, are generated from the spec. The ultimate goal is to make it easy to add new endpoints and add examples if desired.

For now, it's a mess, until we really decide what we want. But for now, I just wanted to get this started.

The full spec is currently here: https://github.com/Chew/RA-api-docs/blob/feat/v2-docs/docs/v2/retroachievements.json

[wescopeland]

I have a few goals for the V2 API documentation:

• The OpenAPI spec should be generated in the RAWeb repo.
• Static types for TS / Kotlin / etc consumers can be generated from this OpenAPI spec.
• We can use something like Scalar for docs generation.

A big open question is how the spec will actually get published. I'm thinking maybe we can have a GitHub Action that emits openapi.json upon commits to RAWeb's release branch, but I'm not 100% sure yet on this approach.

[WedgeSparda]

Hi, I've been playing around for a while with the API V2 to create a Swift client for it. I started working while looking to the PRs adding the new V2 endpoints and then I saw the OpenAPI implementation, which is great.

I want to ask:

• This is a WIP, right? We should expect changes even for the already working endpoints?
• How is the OpenAPI json generated?

My intention is to use the Apple's Swift OpenAPI Generator to create a client which I'll wrap around a more convenient set of functions, because I saw some potential problems using the raw client, like allowing to select which fields should be returned for each resource, which in Swift would be translated in an Optionals Hell.

[wescopeland]

Hi,

The OpenAPI JSON is generated in RAWeb. See: RetroAchievements/RAWeb#5158

The V2 API is WIP, but is nearing a beta release. Pretty much the only thing standing in the way of a beta at the moment is getting docs online, which I haven't had time to take care of. Changes should still be expected, but I don't anticipate major changes to response shapes from here unless we discover a performance concern.