Split lichess-api.yaml

[tors42]

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. 😅

[tors42]

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... 😅

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]

🤯 🙈

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]

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.