Doc response samples and API mismatch

[PesiTheWizard]

• [x] https://lichess.org/api#tag/Challenges/operation/challengeCreate The example fields are under a "challenge" parent, and there's a "socketVersion". Neither are mentioned in the example.
• [x] https://lichess.org/api#tag/Arena-tournaments/operation/apiTournament The example makes mention of "secondsToFinish", "isFinished", "isRecentlyFinished", "podium", "stats", "pairingsClosed", "duels", "standings" and "featured"; none of which appear here.
• [ ] https://lichess.org/api#tag/Bot/operation/apiBotOnline The example shows a title of "NM".
• [x] https://lichess.org/api#tag/Challenges/operation/challengeAi The example claims to respond with 200, actual response is 201; example seems to come from a different endpoint.

The above used a bot:play token

[niklasf]

Thanks for reporting these inconsistencies. Fixed (1) and (4). soketVersion from (1) serves no purpose in the public API for now, so I think it's fine to omit.

[marvk]

There's more. For example, a 200 response to /api/stream/event is defined as

https://github.com/lichess-org/api/blob/d14ec928edcff7046594a0d04fe75f9cddbe5945/doc/specs/lichess-api.yaml#L5140-L5145

Picking one, GameStartEvent is described as

https://github.com/lichess-org/api/blob/d14ec928edcff7046594a0d04fe75f9cddbe5945/doc/specs/lichess-api.yaml#L10346-L10353

which contains a GameEventInfo, which in turn is described as

https://github.com/lichess-org/api/blob/d14ec928edcff7046594a0d04fe75f9cddbe5945/doc/specs/lichess-api.yaml#L10307-L10344

However, looking at the gameStart example from here

https://github.com/lichess-org/api/blob/d14ec928edcff7046594a0d04fe75f9cddbe5945/doc/specs/lichess-api.yaml#L5153-L5154

one discovers there are a lot more undocumented fields possibly returned by the API, for which the definition isn't know:

https://github.com/lichess-org/api/blob/d14ec928edcff7046594a0d04fe75f9cddbe5945/doc/specs/lichess-api.yaml#L10888-L10913

In addition, it's hard or impossible to discern when fields are nullable. Unfortunately these issues make it really hard to write a consistent client, and pretty much impossible to generate one with OpenAPI Generator. Is there a place in (presumably) the lila repository where more reliable information can be found for the moment?

---

Edit:

Also, the example structure isn't even correct: Here's a real json object received from the API. The compat field isn't part of the challenge object, unlike in the example:

{
  "challenge": {
    "challenger": {    ...    },
    "color": "random",
    "destUser": {    ...    },
    "finalColor": "black",
    "id": "GqB3EN2W",
    "perf": {    ...    },
    "rated": false,
    "speed": "blitz",
    "status": "created",
    "timeControl": {    ...    },
    "url": "https://lichess.org/GqB3EN2W",
    "variant": {    ...    }
  },
  "compat": {
    "board": true,
    "bot": true
  },
  "type": "challenge"
}

Here's the example for a challenge:

https://github.com/lichess-org/api/blob/d14ec928edcff7046594a0d04fe75f9cddbe5945/doc/specs/lichess-api.yaml#L10734-L10783

[benediktwerner]

Yes, the lila repository contains the real definitions. In many cases, there is a JsonView class/file which handles the serialization. For the events stream, it's done here: https://github.com/lichess-org/lila/blob/master/modules/api/src/main/EventStream.scala.

You are very welcome to contribute PRs to improve the specification. Having it accurate and complete enough to allow automatic client generation has been discussed a bit here and there and definitely would be really cool but so far nobody has had the time and interest to make major improvements in this area.

[marvk]

@benediktwerner Yeah, I got to EventStream.scala yesterday also. I think the very manual way json is generated in lila is problematic for accurate documentation. To achieve accurate documentation, I think generating the API should be preferred, however, it looks like a massive effort. Just for describing the object schemas, you'd probably have to lift every returned json type into it's own data class, and annotate accordingly. When working in Spring, you can then annotate each rest method accordingly to generate an accurate API while generating the json from the data classes with Swagger.

In general, I think investing effort into automatic generation is worthwhile because it saves a lot of work and trouble in the long term.

It might be something I can contribute to, though I'm not versed in Scala at all unfortunately.

[jalpp]

Hey all any reason why task 3 is not finished?

[jalpp]

I can work on this