From 3dd47dcbba00deddbc0be96aba15727fe4984bdb Mon Sep 17 00:00:00 2001 From: Twinki Date: Sat, 12 Oct 2024 23:49:39 -0400 Subject: [PATCH] Organize operations into tags & Tweak ReDocly display settings # Motivations In preparation for better documentation all of the operations could be sorted into relevant tags # Modifications - Add tags for better visual documentation organization - Expand all JSON samples by default - Expand all schemas by default - Stop sorting operations alphabetically --- .../applyAdvancedGameSettings.yml | 2 + .../applyServerOptions/applyServerOptions.yml | 2 + openapi/functions/claimServer/claimServer.yml | 2 + .../functions/createNewGame/createNewGame.yml | 2 + .../deleteSaveFile/deleteSaveFile.yml | 2 + .../deleteSaveSession/deleteSaveSession.yml | 2 + .../downloadSaveGame/downloadSaveGame.yml | 2 + .../enumerateSessions/enumerateSessions.yml | 2 + .../getAdvancedGameSettings.yml | 2 + .../getServerOptions/getServerOptions.yml | 2 + openapi/functions/healthCheck/healthCheck.yml | 2 + openapi/functions/loadGame/loadGame.yml | 2 + .../functions/passwordLogin/passwordLogin.yml | 2 + .../passwordlessLogin/passwordlessLogin.yml | 2 + .../queryServerState/queryServerState.yml | 2 + .../functions/renameServer/renameServer.yml | 2 + openapi/functions/runCommand/runCommand.yml | 2 + openapi/functions/saveGame/saveGame.yml | 2 + .../setAdminPassword/setAdminPassword.yml | 2 + .../setAutoLoadSessionName.yml | 2 + .../setClientPassword/setClientPassword.yml | 2 + openapi/functions/shutdown/shutdown.yml | 2 + .../uploadSaveGame/uploadSaveGame.yml | 2 + .../verifyAuthenticationToken.yml | 2 + openapi/openapi.yml | 92 ++++++++++++------- redocly.yml | 3 + 26 files changed, 112 insertions(+), 31 deletions(-) diff --git a/openapi/functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml b/openapi/functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml index 745fb0a..1bb53ab 100644 --- a/openapi/functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml +++ b/openapi/functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml @@ -3,6 +3,8 @@ post: operationId: ApplyAdvancedGameSettings description: | Applies new values to the provided Advanced Game Settings properties. Will automatically enable Advanced Game Settings for the currently loaded save if they are not enabled already. + tags: + - Game Settings security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/applyServerOptions/applyServerOptions.yml b/openapi/functions/applyServerOptions/applyServerOptions.yml index 91e858c..d2be5d8 100644 --- a/openapi/functions/applyServerOptions/applyServerOptions.yml +++ b/openapi/functions/applyServerOptions/applyServerOptions.yml @@ -3,6 +3,8 @@ post: operationId: ApplyServerOptions description: | Applies new Server Options to the Dedicated Server. Requires Admin privileges. + tags: + - Server Options security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/claimServer/claimServer.yml b/openapi/functions/claimServer/claimServer.yml index 5fd5dc5..3f0cbc6 100644 --- a/openapi/functions/claimServer/claimServer.yml +++ b/openapi/functions/claimServer/claimServer.yml @@ -3,6 +3,8 @@ post: operationId: ClaimServer description: | Claims this Dedicated Server if it is not claimed. Requires InitialAdmin privilege level, which can only be acquired by attempting passwordless login while the server does not have an Admin Password set, e.g. it is not claimed yet. Function does not return any data in case of success, and the server is claimed. The client should drop InitialAdmin privileges after that and use returned AuthenticationToken instead, and update it's cached server game state by calling QueryServerState. + tags: + - Setup security: - bearerAuth: ['InitialAdmin'] requestBody: diff --git a/openapi/functions/createNewGame/createNewGame.yml b/openapi/functions/createNewGame/createNewGame.yml index 3bb922d..a79b3c8 100644 --- a/openapi/functions/createNewGame/createNewGame.yml +++ b/openapi/functions/createNewGame/createNewGame.yml @@ -3,6 +3,8 @@ post: operationId: CreateNewGame description: | Creates a new session on the Dedicated Server, and immediately loads it. HTTPS API becomes temporarily unavailable when map loading is in progress | Function does not return any data on success. + tags: + - Setup security: - bearerAuth: [] requestBody: diff --git a/openapi/functions/deleteSaveFile/deleteSaveFile.yml b/openapi/functions/deleteSaveFile/deleteSaveFile.yml index a8f377f..7ae8437 100644 --- a/openapi/functions/deleteSaveFile/deleteSaveFile.yml +++ b/openapi/functions/deleteSaveFile/deleteSaveFile.yml @@ -3,6 +3,8 @@ post: operationId: DeleteSaveFile description: | Deletes the existing save game file from the server. Requires Admin privileges. SaveName might be changed to satisfy file system restrictions on file names. Function does not return any data on success. + tags: + - Save Management security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/deleteSaveSession/deleteSaveSession.yml b/openapi/functions/deleteSaveSession/deleteSaveSession.yml index bbd7d1f..8794f07 100644 --- a/openapi/functions/deleteSaveSession/deleteSaveSession.yml +++ b/openapi/functions/deleteSaveSession/deleteSaveSession.yml @@ -3,6 +3,8 @@ post: operationId: DeleteSaveSession description: | Deletes all save files belonging to the specific session name. Requires Admin privileges. SessionName must be a valid session name with at least one saved save game file belonging to it. Function does not return any data on success. + tags: + - Save Management security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/downloadSaveGame/downloadSaveGame.yml b/openapi/functions/downloadSaveGame/downloadSaveGame.yml index 8ef388c..ab93ef9 100644 --- a/openapi/functions/downloadSaveGame/downloadSaveGame.yml +++ b/openapi/functions/downloadSaveGame/downloadSaveGame.yml @@ -3,6 +3,8 @@ post: operationId: DownloadSaveGame description: | Downloads save game with the given name from the Dedicated Server. Requires Admin privileges. This function responds with the file attachment containing the save game file on success, and with normal error response in case of error. + tags: + - Save Management security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/enumerateSessions/enumerateSessions.yml b/openapi/functions/enumerateSessions/enumerateSessions.yml index e1c6b79..5d9e3cc 100644 --- a/openapi/functions/enumerateSessions/enumerateSessions.yml +++ b/openapi/functions/enumerateSessions/enumerateSessions.yml @@ -3,6 +3,8 @@ post: operationId: EnumerateSessions description: | Enumerates all save game files available on the Dedicated Server. Requires Admin privileges. Function does not require any additional parameters. + tags: + - Save Management security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/getAdvancedGameSettings/getAdvancedGameSettings.yml b/openapi/functions/getAdvancedGameSettings/getAdvancedGameSettings.yml index 27110af..73ed6e3 100644 --- a/openapi/functions/getAdvancedGameSettings/getAdvancedGameSettings.yml +++ b/openapi/functions/getAdvancedGameSettings/getAdvancedGameSettings.yml @@ -3,6 +3,8 @@ post: operationId: GetAdvancedGameSettings description: | Retrieves currently applied advanced game settings. Does not require input parameters. + tags: + - Game Settings security: - bearerAuth: [] requestBody: diff --git a/openapi/functions/getServerOptions/getServerOptions.yml b/openapi/functions/getServerOptions/getServerOptions.yml index 3b15d00..5241d05 100644 --- a/openapi/functions/getServerOptions/getServerOptions.yml +++ b/openapi/functions/getServerOptions/getServerOptions.yml @@ -3,6 +3,8 @@ post: operationId: GetServerOptions description: | Retrieves currently applied server options and server options that are still pending application (because of needing session or server restart) Does not require input parameters. + tags: + - Server Options security: - bearerAuth: [] requestBody: diff --git a/openapi/functions/healthCheck/healthCheck.yml b/openapi/functions/healthCheck/healthCheck.yml index d4ac905..27d7173 100644 --- a/openapi/functions/healthCheck/healthCheck.yml +++ b/openapi/functions/healthCheck/healthCheck.yml @@ -2,6 +2,8 @@ post: summary: Health Check operationId: HealthCheck description: Performs a health check on the Dedicated Server API. Allows passing additional data between Modded Dedicated Server and Modded Game Client. This function requires no Authentication. + tags: + - Server Status security: - {} requestBody: diff --git a/openapi/functions/loadGame/loadGame.yml b/openapi/functions/loadGame/loadGame.yml index c52903e..7d4563a 100644 --- a/openapi/functions/loadGame/loadGame.yml +++ b/openapi/functions/loadGame/loadGame.yml @@ -3,6 +3,8 @@ post: operationId: LoadGame description: | Loads the save game file by name, optionally with Advanced Game Settings enabled. Requires Admin privileges. Dedicated Server HTTPS API will become temporarily unavailable when save game is being loaded. Function does not return any data on succcess. + tags: + - Save Management security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/passwordLogin/passwordLogin.yml b/openapi/functions/passwordLogin/passwordLogin.yml index fa56a3c..355169a 100644 --- a/openapi/functions/passwordLogin/passwordLogin.yml +++ b/openapi/functions/passwordLogin/passwordLogin.yml @@ -3,6 +3,8 @@ post: operationId: PasswordLogin description: | Attempts to log in to the Dedicated Server as a player using either Admin Password or Client Protection Password. This function requires no Authentication. + tags: + - Authorization security: - {} requestBody: diff --git a/openapi/functions/passwordlessLogin/passwordlessLogin.yml b/openapi/functions/passwordlessLogin/passwordlessLogin.yml index e51d322..6df0b73 100644 --- a/openapi/functions/passwordlessLogin/passwordlessLogin.yml +++ b/openapi/functions/passwordlessLogin/passwordlessLogin.yml @@ -3,6 +3,8 @@ post: operationId: PasswordlessLogin description: | Attempts to perform a passwordless login to the Dedicated Server as a player. Passwordless login is possible if the Dedicated Server is not claimed, or if Client Protection Password is not set for the Dedicated Server. This function requires no Authentication. + tags: + - Authorization security: - {} requestBody: diff --git a/openapi/functions/queryServerState/queryServerState.yml b/openapi/functions/queryServerState/queryServerState.yml index 085d4c5..78c0a80 100644 --- a/openapi/functions/queryServerState/queryServerState.yml +++ b/openapi/functions/queryServerState/queryServerState.yml @@ -3,6 +3,8 @@ post: operationId: QueryServerState description: | Retrieves the current state of the Dedicated Server. Does not require any input parameters. + tags: + - Server Status security: - bearerAuth: [] requestBody: diff --git a/openapi/functions/renameServer/renameServer.yml b/openapi/functions/renameServer/renameServer.yml index 5e8c8d2..1817da2 100644 --- a/openapi/functions/renameServer/renameServer.yml +++ b/openapi/functions/renameServer/renameServer.yml @@ -3,6 +3,8 @@ post: operationId: RenameServer description: | Renames the Dedicated Server once it has been claimed. Requires Admin privileges. Function does not return any data on success. + tags: + - Server Options security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/runCommand/runCommand.yml b/openapi/functions/runCommand/runCommand.yml index 3201bc2..3b5d416 100644 --- a/openapi/functions/runCommand/runCommand.yml +++ b/openapi/functions/runCommand/runCommand.yml @@ -3,6 +3,8 @@ post: operationId: RunCommand description: | Runs the given Console Command on the Dedicated Server, and returns it's output to the Console. Requires Admin privileges. + tags: + - Server Actions security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/saveGame/saveGame.yml b/openapi/functions/saveGame/saveGame.yml index 5183592..b87a990 100644 --- a/openapi/functions/saveGame/saveGame.yml +++ b/openapi/functions/saveGame/saveGame.yml @@ -3,6 +3,8 @@ post: operationId: SaveGame description: | Saves the currently loaded session into the new save game file named as the argument. Requires Admin privileges. SaveName might be changed to satisfy file system restrictions on file names. Function does not return any data on success. + tags: + - Save Management security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/setAdminPassword/setAdminPassword.yml b/openapi/functions/setAdminPassword/setAdminPassword.yml index 739df8e..a0d1c1d 100644 --- a/openapi/functions/setAdminPassword/setAdminPassword.yml +++ b/openapi/functions/setAdminPassword/setAdminPassword.yml @@ -3,6 +3,8 @@ post: operationId: SetAdminPassword description: | Updates the currently set Admin Password. This will invalidate all previously issued Client and Admin authentication tokens. Requires Admin privileges. Function does not return any data on success. + tags: + - Authorization security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/setAutoLoadSessionName/setAutoLoadSessionName.yml b/openapi/functions/setAutoLoadSessionName/setAutoLoadSessionName.yml index c48af8e..e1ea40e 100644 --- a/openapi/functions/setAutoLoadSessionName/setAutoLoadSessionName.yml +++ b/openapi/functions/setAutoLoadSessionName/setAutoLoadSessionName.yml @@ -3,6 +3,8 @@ post: operationId: SetAutoLoadSessionName description: | Updates the name of the session that the Dedicated Server will automatically load on startup. Does not change currently loaded session. Requires Admin privileges. Function does not return any data on success. + tags: + - Save Management security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/setClientPassword/setClientPassword.yml b/openapi/functions/setClientPassword/setClientPassword.yml index 811bc9c..5fc94b0 100644 --- a/openapi/functions/setClientPassword/setClientPassword.yml +++ b/openapi/functions/setClientPassword/setClientPassword.yml @@ -3,6 +3,8 @@ post: operationId: SetClientPassword description: | Updates the currently set Client Protection Password. This will invalidate all previously issued Client authentication tokens. Pass empty string to remove the password, and let anyone join the server as Client. Requres Admin privileges. Function does not return any data on success. + tags: + - Authorization security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/shutdown/shutdown.yml b/openapi/functions/shutdown/shutdown.yml index 9484767..b5f5ff3 100644 --- a/openapi/functions/shutdown/shutdown.yml +++ b/openapi/functions/shutdown/shutdown.yml @@ -3,6 +3,8 @@ post: operationId: Shutdown description: | Shuts down the Dedicated Server. If automatic restart script is setup, this allows restarting the server to apply new settings or update. Requires Admin privileges. Shutdowns initiated by remote hosts are logged with their IP and their token. Function does not return any data on success, and does not take any parameters. + tags: + - Server Actions security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/uploadSaveGame/uploadSaveGame.yml b/openapi/functions/uploadSaveGame/uploadSaveGame.yml index 303c9f0..c58cea1 100644 --- a/openapi/functions/uploadSaveGame/uploadSaveGame.yml +++ b/openapi/functions/uploadSaveGame/uploadSaveGame.yml @@ -3,6 +3,8 @@ post: operationId: UploadSaveGame description: | Shuts down the Dedicated Server. If automatic restart script is setup, this allows restarting the server to apply new settings or update. Requires Admin privileges. Shutdowns initiated by remote hosts are logged with their IP and their token. Function does not return any data on success, and does not take any parameters. + tags: + - Save Management security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/verifyAuthenticationToken/verifyAuthenticationToken.yml b/openapi/functions/verifyAuthenticationToken/verifyAuthenticationToken.yml index 41ea5dc..f83a2c0 100644 --- a/openapi/functions/verifyAuthenticationToken/verifyAuthenticationToken.yml +++ b/openapi/functions/verifyAuthenticationToken/verifyAuthenticationToken.yml @@ -2,6 +2,8 @@ post: summary: Verify Authentication Token operationId: VerifyAuthenticationToken description: Verifies the Authentication token provided to the Dedicated Server API. Returns No Content if the provided token is valid. This function does not require input parameters and does not return any data. + tags: + - Authorization security: - bearerAuth: [] requestBody: diff --git a/openapi/openapi.yml b/openapi/openapi.yml index b3a93c0..9fd616d 100644 --- a/openapi/openapi.yml +++ b/openapi/openapi.yml @@ -17,14 +17,34 @@ components: scheme: bearer bearerFormat: JWT +tags: +- name: Setup + description: Authorization +- name: Authorization + description: Authorization +- name: Server Status + description: Server Status +- name: Server Actions + description: Save Management +- name: Server Options + description: Server Options +- name: Game Settings + description: Game Settings +- name: Save Management + description: Save Management paths: - # HealthCheck - '/api/v1/?function=HealthCheck': - $ref: functions/healthCheck/healthCheck.yml - # VerifyAuthenticationToken - '/api/v1/?function=VerifyAuthenticationToken': - $ref: functions/verifyAuthenticationToken/verifyAuthenticationToken.yml + # --- Setup + + # ClaimServer + '/api/v1/?function=ClaimServer': + $ref: functions/claimServer/claimServer.yml + + # CreateNewGame + '/api/v1/?function=CreateNewGame': + $ref: functions/createNewGame/createNewGame.yml + + # --- Authorization # PasswordlessLogin '/api/v1/?function=PasswordlessLogin': @@ -34,13 +54,29 @@ paths: '/api/v1/?function=PasswordLogin': $ref: functions/passwordLogin/passwordLogin.yml + # SetClientPassword + '/api/v1/?function=SetClientPassword': + $ref: functions/setClientPassword/setClientPassword.yml + + # SetAdminPassword + '/api/v1/?function=SetAdminPassword': + $ref: functions/setAdminPassword/setAdminPassword.yml + + # VerifyAuthenticationToken + '/api/v1/?function=VerifyAuthenticationToken': + $ref: functions/verifyAuthenticationToken/verifyAuthenticationToken.yml + + # --- Server Status + + # HealthCheck + '/api/v1/?function=HealthCheck': + $ref: functions/healthCheck/healthCheck.yml + # QueryServerState '/api/v1/?function=QueryServerState': $ref: functions/queryServerState/queryServerState.yml - # GetServerOptions - '/api/v1/?function=GetServerOptions': - $ref: functions/getServerOptions/getServerOptions.yml + # --- Game Settings # GetAdvancedGameSettings '/api/v1/?function=GetAdvancedGameSettings': @@ -50,25 +86,7 @@ paths: '/api/v1/?function=ApplyAdvancedGameSettings': $ref: functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml - # ClaimServer - '/api/v1/?function=ClaimServer': - $ref: functions/claimServer/claimServer.yml - - # RenameServer - '/api/v1/?function=RenameServer': - $ref: functions/renameServer/renameServer.yml - - # SetClientPassword - '/api/v1/?function=SetClientPassword': - $ref: functions/setClientPassword/setClientPassword.yml - - # SetAdminPassword - '/api/v1/?function=SetAdminPassword': - $ref: functions/setAdminPassword/setAdminPassword.yml - - # SetAutoLoadSessionName - '/api/v1/?function=SetAutoLoadSessionName': - $ref: functions/setAutoLoadSessionName/setAutoLoadSessionName.yml + # --- Server Actions # RunCommand '/api/v1/?function=RunCommand': @@ -78,13 +96,25 @@ paths: '/api/v1/?function=Shutdown': $ref: functions/shutdown/shutdown.yml + # --- Server Options + + # GetServerOptions + '/api/v1/?function=GetServerOptions': + $ref: functions/getServerOptions/getServerOptions.yml + # ApplyServerOptions '/api/v1/?function=ApplyServerOptions': $ref: functions/applyServerOptions/applyServerOptions.yml - # CreateNewGame - '/api/v1/?function=CreateNewGame': - $ref: functions/createNewGame/createNewGame.yml + # RenameServer + '/api/v1/?function=RenameServer': + $ref: functions/renameServer/renameServer.yml + + # --- Save Management + + # SetAutoLoadSessionName + '/api/v1/?function=SetAutoLoadSessionName': + $ref: functions/setAutoLoadSessionName/setAutoLoadSessionName.yml # SaveGame '/api/v1/?function=SaveGame': diff --git a/redocly.yml b/redocly.yml index 3bb6d0e..637ebbd 100644 --- a/redocly.yml +++ b/redocly.yml @@ -11,3 +11,6 @@ rules: theme: openapi: htmlTemplate: ./docs/index.html + jsonSampleExpandLevel: all + schemaExpansionLevel: all + sortOperationsAlphabetically: false