search

lichess-org / api

Lichess API documentation and examples
https://lichess.org/api
GNU Affero General Public License v3.0
413 stars 140 forks source link

Split lichess-api.yaml #309

Closed tors42 closed 5 months ago

tors42 commented 5 months ago

I saw a blog post about splitting huge openapi files into smaller, maybe more managable, parts, https://davidgarcia.dev/posts/how-to-split-open-api-spec-into-multiple-files/

I figured there are both pros and cons with splitting a single openapi file...

To make it easier to get a feel for how such a split could work, I figured I'd just try it out on a branch.

lichess-api.yaml went from 11000 to 1000 lines, and from 1 to 231 in file count...

I do not know if this is a win or if it is a fail. :sweat_smile:

tors42 commented 5 months ago

Oh, the remaining 2 warnings from the lint run,

oas3-unused-component  Potentially unused component has been detected.  components.schemas.$ref
oas3-unused-component  Potentially unused component has been detected.  components.examples.$ref

might possibly be false positives... :sweat_smile:

This rule may identify false positives when linting a specification that acts as a library (a container storing reusable objects, leveraged by other specifications that reference those objects). https://meta.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#oas3-unused-component

tors42 commented 5 months ago

:exploding_head: :see_no_evil:

tree --filesfirst specs/ ``` specs/ ├── favicon.ico ├── lichess-api.yaml ├── examples │   ├── challengeCanceled.yaml │   ├── challengeDeclined.yaml │   ├── challenge.yaml │   ├── chatLineSpectator.yaml │   ├── chatLine.yaml │   ├── gameFinish.yaml │   ├── gameFull.yaml │   ├── gameStart.yaml │   ├── gameStateResign.yaml │   ├── gameState.yaml │   ├── _index.yaml │   ├── opponentGoneFalse.yaml │   └── opponentGoneTrue.yaml ├── schemas │   ├── ArenaPerf.yaml │   ├── ArenaPosition.yaml │   ├── ArenaRatingObj.yaml │   ├── ArenaStatus.yaml │   ├── ArenaTournaments.yaml │   ├── ArenaTournamentVariantIsKey.yaml │   ├── ArenaTournament.yaml │   ├── BroadcastForm.yaml │   ├── BroadcastMyRound.yaml │   ├── BroadcastRound.yaml │   ├── BroadcastTour.yaml │   ├── BulkPairing.yaml │   ├── ChallengeCanceledEvent.yaml │   ├── ChallengeCanceledJson.yaml │   ├── ChallengeCancelJson.yaml │   ├── ChallengeDeclinedEvent.yaml │   ├── ChallengeEvent.yaml │   ├── ChallengeJson.yaml │   ├── ChallengeOpenJson.yaml │   ├── ChallengeUser.yaml │   ├── ChatLineEvent.yaml │   ├── Clock.yaml │   ├── Count.yaml │   ├── Crosstable.yaml │   ├── Error.yaml │   ├── ExternalEngineRegistration.yaml │   ├── ExternalEngineWork.yaml │   ├── ExternalEngine.yaml │   ├── FromPositionFEN.yaml │   ├── GameChat.yaml │   ├── GameEventInfo.yaml │   ├── GameEventPlayer.yaml │   ├── GameFinishEvent.yaml │   ├── GameFullEvent.yaml │   ├── GameJson.yaml │   ├── GamePgn.yaml │   ├── GameStartEvent.yaml │   ├── GameStateEvent.yaml │   ├── GameStatus.yaml │   ├── GameStream.yaml │   ├── GameUser.yaml │   ├── _index.yaml │   ├── Leaderboard.yaml │   ├── LightUserOnline.yaml │   ├── LightUser.yaml │   ├── MasterGamePgn.yaml │   ├── MoveStream.yaml │   ├── Move.yaml │   ├── NotFound.yaml │   ├── OAuthError.yaml │   ├── Ok.yaml │   ├── OpeningExplorerJson.yaml │   ├── OpeningExplorerPlayerJson.yaml │   ├── OpponentGone.yaml │   ├── PerfStat.yaml │   ├── Perfs.yaml │   ├── PerfType.yaml │   ├── Perf.yaml │   ├── PlayTime.yaml │   ├── Profile.yaml │   ├── PuzzleAndGame.yaml │   ├── PuzzleDashboardJson.yaml │   ├── PuzzleModePerf.yaml │   ├── PuzzleRaceJson.yaml │   ├── PuzzleRoundJson.yaml │   ├── RatingHistory.yaml │   ├── Simul.yaml │   ├── Speed.yaml │   ├── StormDashboardJson.yaml │   ├── StudyImportPgnChapters.yaml │   ├── StudyMetadata.yaml │   ├── StudyPgn.yaml │   ├── SwissTournament.yaml │   ├── SwissUnauthorisedEdit.yaml │   ├── TablebaseJson.yaml │   ├── TeamPaginatorJson.yaml │   ├── TeamRequestWithUser.yaml │   ├── TeamRequest.yaml │   ├── Team.yaml │   ├── Timeline.yaml │   ├── Title.yaml │   ├── Top10s.yaml │   ├── UciVariant.yaml │   ├── UserExtended.yaml │   ├── UserNote.yaml │   ├── UserPreferences.yaml │   ├── User.yaml │   ├── VariantKey.yaml │   └── Variant.yaml └── tags ├── account │   ├── api-account-email.yaml │   ├── api-account-kid.yaml │   ├── api-account-preferences.yaml │   ├── api-account.yaml │   └── api-timeline.yaml ├── analysis │   └── api-cloud-eval.yaml ├── arenatournaments │   ├── api-tournament-id-games.yaml │   ├── api-tournament-id-join.yaml │   ├── api-tournament-id-results.yaml │   ├── api-tournament-id-teams.yaml │   ├── api-tournament-id-terminate.yaml │   ├── api-tournament-id-withdraw.yaml │   ├── api-tournament-id.yaml │   ├── api-tournament-team-battle-id.yaml │   ├── api-tournament.yaml │   └── api-user-username-tournament-created.yaml ├── board │   ├── api-board-game-gameId-abort.yaml │   ├── api-board-game-gameId-berserk.yaml │   ├── api-board-game-gameId-chat.yaml │   ├── api-board-game-gameId-claim-victory.yaml │   ├── api-board-game-gameId-draw-accept.yaml │   ├── api-board-game-gameId-move-move.yaml │   ├── api-board-game-gameId-resign.yaml │   ├── api-board-game-gameId-takeback-accept.yaml │   ├── api-board-game-stream-gameId.yaml │   ├── api-board-seek.yaml │   └── api-stream-event.yaml ├── bot │   ├── api-bot-account-upgrade.yaml │   ├── api-bot-game-gameId-abort.yaml │   ├── api-bot-game-gameId-chat.yaml │   ├── api-bot-game-gameId-draw-accept.yaml │   ├── api-bot-game-gameId-move-move.yaml │   ├── api-bot-game-gameId-resign.yaml │   ├── api-bot-game-stream-gameId.yaml │   └── api-bot-online.yaml ├── broadcasts │   ├── api-broadcast-broadcastTournamentId.pgn.yaml │   ├── api-broadcast-broadcastTournamentSlug-broadcastRoundSlug-broadcastRoundId.yaml │   ├── api-broadcast-my-rounds.yaml │   ├── api-broadcast-round-broadcastRoundId.pgn.yaml │   ├── api-broadcast.yaml │   ├── api-stream-broadcast-round-broadcastRoundId.pgn.yaml │   ├── broadcast-broadcastTournamentId-edit.yaml │   ├── broadcast-broadcastTournamentId-new.yaml │   ├── broadcast-new.yaml │   ├── broadcast-round-broadcastRoundId-edit.yaml │   ├── broadcast-round-broadcastRoundId-push.yaml │   └── broadcast-slug-broadcastTournamentId.yaml ├── bulkpairings │   ├── api-bulk-pairing-id-start-clocks.yaml │   ├── api-bulk-pairing-id.yaml │   └── api-bulk-pairing.yaml ├── challenges │   ├── api-challenge-ai.yaml │   ├── api-challenge-challengeId-accept.yaml │   ├── api-challenge-challengeId-cancel.yaml │   ├── api-challenge-challengeId-decline.yaml │   ├── api-challenge-gameId-start-clocks.yaml │   ├── api-challenge-open.yaml │   ├── api-challenge-username.yaml │   ├── api-challenge.yaml │   ├── api-round-gameId-add-time-seconds.yaml │   └── api-token-admin-challenge.yaml ├── externalengine │   ├── api-external-engine-id-analyse.yaml │   ├── api-external-engine-id.yaml │   ├── api-external-engine-work-id.yaml │   ├── api-external-engine-work.yaml │   └── api-external-engine.yaml ├── games │   ├── api-account-playing.yaml │   ├── api-games-export-_ids.yaml │   ├── api-games-export-imports.yaml │   ├── api-games-user-username.yaml │   ├── api-import.yaml │   ├── api-stream-game-id.yaml │   ├── api-stream-games-by-users.yaml │   ├── api-stream-games-streamId-add.yaml │   ├── api-stream-games-streamId.yaml │   ├── api-user-username-current-game.yaml │   └── game-export-gameId.yaml ├── messaging │   └── inbox-username.yaml ├── oauth │   ├── api-token-test.yaml │   ├── api-token.yaml │   └── oauth.yaml ├── openingexplorer │   ├── lichess.yaml │   ├── master-pgn-gameId.yaml │   ├── masters.yaml │   └── player.yaml ├── puzzles │   ├── api-puzzle-activity.yaml │   ├── api-puzzle-daily.yaml │   ├── api-puzzle-dashboard-days.yaml │   ├── api-puzzle-id.yaml │   ├── api-racer.yaml │   └── api-storm-dashboard-username.yaml ├── relations │   ├── api-rel-following.yaml │   ├── api-rel-follow-username.yaml │   └── api-rel-unfollow-username.yaml ├── simuls │   └── api-simul.yaml ├── studies │   ├── api-study-by-username.yaml │   ├── api-study-studyId-chapterId.pgn.yaml │   ├── api-study-studyId-import-pgn.yaml │   ├── api-study-studyId.pgn.yaml │   └── study-by-username-export.pgn.yaml ├── swisstournaments │   ├── api-swiss-id-edit.yaml │   ├── api-swiss-id-games.yaml │   ├── api-swiss-id-join.yaml │   ├── api-swiss-id-results.yaml │   ├── api-swiss-id-schedule-next-round.yaml │   ├── api-swiss-id-terminate.yaml │   ├── api-swiss-id-withdraw.yaml │   ├── api-swiss-id.yaml │   ├── api-swiss-new-teamId.yaml │   └── swiss-id.trf.yaml ├── tablebase │   ├── antichess.yaml │   ├── atomic.yaml │   └── standard.yaml ├── teams │   ├── api-team-all.yaml │   ├── api-team-of-username.yaml │   ├── api-team-search.yaml │   ├── api-team-teamId-arena.yaml │   ├── api-team-teamId-kick-userId.yaml │   ├── api-team-teamId-requests.yaml │   ├── api-team-teamId-request-userId-accept.yaml │   ├── api-team-teamId-request-userId-decline.yaml │   ├── api-team-teamId-swiss.yaml │   ├── api-team-teamId-users.yaml │   ├── api-team-teamId.yaml │   ├── team-teamId-join.yaml │   ├── team-teamId-pm-all.yaml │   └── team-teamId-quit.yaml ├── tv │   ├── api-tv-channels.yaml │   ├── api-tv-channel.yaml │   └── api-tv-feed.yaml └── users ├── api-crosstable-user1-user2.yaml ├── api-player-autocomplete.yaml ├── api-player-top-nb-perfType.yaml ├── api-player.yaml ├── api-streamer-live.yaml ├── api-users-status.yaml ├── api-users.yaml ├── api-user-username-activity.yaml ├── api-user-username-note.yaml ├── api-user-username-perf-perf.yaml ├── api-user-username-rating-history.yaml └── api-user-username.yaml 26 directories, 245 files ```
ornicar commented 5 months ago

been staring at it for a moment, and I can't decide whether it's better or worse than the single file.

I guess we'll try it out and see.