Doc response samples and API mismatch
PesiTheWizard opened this issue · comments
- 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. - 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". - 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
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.
There's more. For example, a 200 response to /api/stream/event is defined as
api/doc/specs/lichess-api.yaml
Lines 5140 to 5145 in d14ec92
Picking one, GameStartEvent is described as
api/doc/specs/lichess-api.yaml
Lines 10346 to 10353 in d14ec92
which contains a GameEventInfo, which in turn is described as
api/doc/specs/lichess-api.yaml
Lines 10307 to 10344 in d14ec92
However, looking at the gameStart example from here
api/doc/specs/lichess-api.yaml
Lines 5153 to 5154 in d14ec92
one discovers there are a lot more undocumented fields possibly returned by the API, for which the definition isn't know:
api/doc/specs/lichess-api.yaml
Lines 10888 to 10913 in d14ec92
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:
api/doc/specs/lichess-api.yaml
Lines 10734 to 10783 in d14ec92
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.
@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.
Hey all any reason why task 3 is not finished?
I can work on this