From 3dd47dcbba00deddbc0be96aba15727fe4984bdb Mon Sep 17 00:00:00 2001 From: Twinki Date: Sat, 12 Oct 2024 23:49:39 -0400 Subject: [PATCH 1/3] 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 From 3665a445bde91ed62900da0be253d47364ffcc2c Mon Sep 17 00:00:00 2001 From: Twinki Date: Sun, 13 Oct 2024 13:21:42 -0400 Subject: [PATCH 2/3] Adjustments --- .../applyAdvancedGameSettings.yml | 2 +- .../applyServerOptions/applyServerOptions.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 +- .../queryServerState/queryServerState.yml | 2 +- .../functions/renameServer/renameServer.yml | 2 +- openapi/functions/runCommand/runCommand.yml | 2 +- openapi/functions/saveGame/saveGame.yml | 2 +- .../setAutoLoadSessionName.yml | 3 +- openapi/functions/shutdown/shutdown.yml | 2 +- .../uploadSaveGame/uploadSaveGame.yml | 2 +- openapi/openapi.yml | 102 +++++++++--------- 18 files changed, 69 insertions(+), 68 deletions(-) diff --git a/openapi/functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml b/openapi/functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml index 1bb53ab..4ef9d00 100644 --- a/openapi/functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml +++ b/openapi/functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml @@ -4,7 +4,7 @@ post: 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 + - Game security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/applyServerOptions/applyServerOptions.yml b/openapi/functions/applyServerOptions/applyServerOptions.yml index d2be5d8..aeafc8b 100644 --- a/openapi/functions/applyServerOptions/applyServerOptions.yml +++ b/openapi/functions/applyServerOptions/applyServerOptions.yml @@ -4,7 +4,7 @@ post: description: | Applies new Server Options to the Dedicated Server. Requires Admin privileges. tags: - - Server Options + - Server security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/deleteSaveFile/deleteSaveFile.yml b/openapi/functions/deleteSaveFile/deleteSaveFile.yml index 7ae8437..5e9cabc 100644 --- a/openapi/functions/deleteSaveFile/deleteSaveFile.yml +++ b/openapi/functions/deleteSaveFile/deleteSaveFile.yml @@ -4,7 +4,7 @@ post: 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 + - Saves security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/deleteSaveSession/deleteSaveSession.yml b/openapi/functions/deleteSaveSession/deleteSaveSession.yml index 8794f07..49e297a 100644 --- a/openapi/functions/deleteSaveSession/deleteSaveSession.yml +++ b/openapi/functions/deleteSaveSession/deleteSaveSession.yml @@ -4,7 +4,7 @@ post: 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 + - Sessions security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/downloadSaveGame/downloadSaveGame.yml b/openapi/functions/downloadSaveGame/downloadSaveGame.yml index ab93ef9..33db7f6 100644 --- a/openapi/functions/downloadSaveGame/downloadSaveGame.yml +++ b/openapi/functions/downloadSaveGame/downloadSaveGame.yml @@ -4,7 +4,7 @@ post: 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 + - Saves security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/enumerateSessions/enumerateSessions.yml b/openapi/functions/enumerateSessions/enumerateSessions.yml index 5d9e3cc..a6cf985 100644 --- a/openapi/functions/enumerateSessions/enumerateSessions.yml +++ b/openapi/functions/enumerateSessions/enumerateSessions.yml @@ -4,7 +4,7 @@ post: description: | Enumerates all save game files available on the Dedicated Server. Requires Admin privileges. Function does not require any additional parameters. tags: - - Save Management + - Sessions security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/getAdvancedGameSettings/getAdvancedGameSettings.yml b/openapi/functions/getAdvancedGameSettings/getAdvancedGameSettings.yml index 73ed6e3..781b720 100644 --- a/openapi/functions/getAdvancedGameSettings/getAdvancedGameSettings.yml +++ b/openapi/functions/getAdvancedGameSettings/getAdvancedGameSettings.yml @@ -4,7 +4,7 @@ post: description: | Retrieves currently applied advanced game settings. Does not require input parameters. tags: - - Game Settings + - Game security: - bearerAuth: [] requestBody: diff --git a/openapi/functions/getServerOptions/getServerOptions.yml b/openapi/functions/getServerOptions/getServerOptions.yml index 5241d05..8067f48 100644 --- a/openapi/functions/getServerOptions/getServerOptions.yml +++ b/openapi/functions/getServerOptions/getServerOptions.yml @@ -4,7 +4,7 @@ post: 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 + - Server security: - bearerAuth: [] requestBody: diff --git a/openapi/functions/healthCheck/healthCheck.yml b/openapi/functions/healthCheck/healthCheck.yml index 27d7173..79990c3 100644 --- a/openapi/functions/healthCheck/healthCheck.yml +++ b/openapi/functions/healthCheck/healthCheck.yml @@ -3,7 +3,7 @@ post: 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 + - Server security: - {} requestBody: diff --git a/openapi/functions/loadGame/loadGame.yml b/openapi/functions/loadGame/loadGame.yml index 7d4563a..0214abf 100644 --- a/openapi/functions/loadGame/loadGame.yml +++ b/openapi/functions/loadGame/loadGame.yml @@ -4,7 +4,7 @@ post: 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 + - Saves security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/queryServerState/queryServerState.yml b/openapi/functions/queryServerState/queryServerState.yml index 78c0a80..d3686e9 100644 --- a/openapi/functions/queryServerState/queryServerState.yml +++ b/openapi/functions/queryServerState/queryServerState.yml @@ -4,7 +4,7 @@ post: description: | Retrieves the current state of the Dedicated Server. Does not require any input parameters. tags: - - Server Status + - Server security: - bearerAuth: [] requestBody: diff --git a/openapi/functions/renameServer/renameServer.yml b/openapi/functions/renameServer/renameServer.yml index 1817da2..6361777 100644 --- a/openapi/functions/renameServer/renameServer.yml +++ b/openapi/functions/renameServer/renameServer.yml @@ -4,7 +4,7 @@ post: description: | Renames the Dedicated Server once it has been claimed. Requires Admin privileges. Function does not return any data on success. tags: - - Server Options + - Server security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/runCommand/runCommand.yml b/openapi/functions/runCommand/runCommand.yml index 3b5d416..6612646 100644 --- a/openapi/functions/runCommand/runCommand.yml +++ b/openapi/functions/runCommand/runCommand.yml @@ -4,7 +4,7 @@ post: description: | Runs the given Console Command on the Dedicated Server, and returns it's output to the Console. Requires Admin privileges. tags: - - Server Actions + - Server security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/saveGame/saveGame.yml b/openapi/functions/saveGame/saveGame.yml index b87a990..6e1246a 100644 --- a/openapi/functions/saveGame/saveGame.yml +++ b/openapi/functions/saveGame/saveGame.yml @@ -4,7 +4,7 @@ post: 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 + - Saves security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/setAutoLoadSessionName/setAutoLoadSessionName.yml b/openapi/functions/setAutoLoadSessionName/setAutoLoadSessionName.yml index e1ea40e..572d2f6 100644 --- a/openapi/functions/setAutoLoadSessionName/setAutoLoadSessionName.yml +++ b/openapi/functions/setAutoLoadSessionName/setAutoLoadSessionName.yml @@ -4,7 +4,8 @@ post: 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 + - Server + - Sessions security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/shutdown/shutdown.yml b/openapi/functions/shutdown/shutdown.yml index b5f5ff3..ff6cb52 100644 --- a/openapi/functions/shutdown/shutdown.yml +++ b/openapi/functions/shutdown/shutdown.yml @@ -4,7 +4,7 @@ post: 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 + - Server security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/functions/uploadSaveGame/uploadSaveGame.yml b/openapi/functions/uploadSaveGame/uploadSaveGame.yml index c58cea1..95398c5 100644 --- a/openapi/functions/uploadSaveGame/uploadSaveGame.yml +++ b/openapi/functions/uploadSaveGame/uploadSaveGame.yml @@ -4,7 +4,7 @@ post: 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 + - Saves security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/openapi.yml b/openapi/openapi.yml index 9fd616d..e877a7f 100644 --- a/openapi/openapi.yml +++ b/openapi/openapi.yml @@ -22,16 +22,14 @@ tags: description: Authorization - name: Authorization description: Authorization -- name: Server Status +- name: Server description: Server Status -- name: Server Actions - description: Save Management -- name: Server Options - description: Server Options -- name: Game Settings +- name: Game description: Game Settings -- name: Save Management - description: Save Management +- name: Saves + description: Saves +- name: Sessions + description: Sessions paths: # --- Setup @@ -66,27 +64,38 @@ paths: '/api/v1/?function=VerifyAuthenticationToken': $ref: functions/verifyAuthenticationToken/verifyAuthenticationToken.yml - # --- Server Status + # --- Sessions + # - Placed here to keep a specific ordering in our generated documentation + + # EnumerateSessions + '/api/v1/?function=EnumerateSessions': + $ref: functions/enumerateSessions/enumerateSessions.yml + + # --- Server # 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 + # ApplyServerOptions + '/api/v1/?function=ApplyServerOptions': + $ref: functions/applyServerOptions/applyServerOptions.yml - # GetAdvancedGameSettings - '/api/v1/?function=GetAdvancedGameSettings': - $ref: functions/getAdvancedGameSettings/getAdvancedGameSettings.yml + # SetAutoLoadSessionName + '/api/v1/?function=SetAutoLoadSessionName': + $ref: functions/setAutoLoadSessionName/setAutoLoadSessionName.yml - # ApplyAdvancedGameSettings - '/api/v1/?function=ApplyAdvancedGameSettings': - $ref: functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml + # QueryServerState + '/api/v1/?function=QueryServerState': + $ref: functions/queryServerState/queryServerState.yml - # --- Server Actions + # RenameServer + '/api/v1/?function=RenameServer': + $ref: functions/renameServer/renameServer.yml # RunCommand '/api/v1/?function=RunCommand': @@ -96,50 +105,41 @@ paths: '/api/v1/?function=Shutdown': $ref: functions/shutdown/shutdown.yml - # --- Server Options + # --- Sessions + # - Placed here to keep a specific ordering in our generated documentation - # GetServerOptions - '/api/v1/?function=GetServerOptions': - $ref: functions/getServerOptions/getServerOptions.yml + # DeleteSaveSession + '/api/v1/?function=DeleteSaveSession': + $ref: functions/deleteSaveSession/deleteSaveSession.yml - # ApplyServerOptions - '/api/v1/?function=ApplyServerOptions': - $ref: functions/applyServerOptions/applyServerOptions.yml + # --- Game - # RenameServer - '/api/v1/?function=RenameServer': - $ref: functions/renameServer/renameServer.yml + # GetAdvancedGameSettings + '/api/v1/?function=GetAdvancedGameSettings': + $ref: functions/getAdvancedGameSettings/getAdvancedGameSettings.yml - # --- Save Management + # ApplyAdvancedGameSettings + '/api/v1/?function=ApplyAdvancedGameSettings': + $ref: functions/applyAdvancedGameSettings/applyAdvancedGameSettings.yml - # SetAutoLoadSessionName - '/api/v1/?function=SetAutoLoadSessionName': - $ref: functions/setAutoLoadSessionName/setAutoLoadSessionName.yml + # --- Saves # SaveGame '/api/v1/?function=SaveGame': $ref: functions/saveGame/saveGame.yml - # DeleteSaveFile - '/api/v1/?function=DeleteSaveFile': - $ref: functions/deleteSaveFile/deleteSaveFile.yml - - # DeleteSaveSession - '/api/v1/?function=DeleteSaveSession': - $ref: functions/deleteSaveSession/deleteSaveSession.yml + # DownloadSaveGame + '/api/v1/?function=DownloadSaveGame': + $ref: functions/downloadSaveGame/downloadSaveGame.yml - # EnumerateSessions - '/api/v1/?function=EnumerateSessions': - $ref: functions/enumerateSessions/enumerateSessions.yml + # UploadSaveGame + '/api/v1/?function=UploadSaveGame': + $ref: functions/uploadSaveGame/uploadSaveGame.yml # LoadGame '/api/v1/?function=LoadGame': $ref: functions/loadGame/loadGame.yml - # UploadSaveGame - '/api/v1/?function=UploadSaveGame': - $ref: functions/uploadSaveGame/uploadSaveGame.yml - - # DownloadSaveGame - '/api/v1/?function=DownloadSaveGame': - $ref: functions/downloadSaveGame/downloadSaveGame.yml + # DeleteSaveFile + '/api/v1/?function=DeleteSaveFile': + $ref: functions/deleteSaveFile/deleteSaveFile.yml From e9b24fb5ae60628fb8fd0f761ba5991144ee1a40 Mon Sep 17 00:00:00 2001 From: Twinki Date: Sun, 13 Oct 2024 13:28:09 -0400 Subject: [PATCH 3/3] Final tweaks --- openapi/functions/claimServer/claimServer.yml | 1 + openapi/functions/createNewGame/createNewGame.yml | 1 + .../setClientPassword/setClientPassword.yml | 1 + openapi/openapi.yml | 14 +++++++------- 4 files changed, 10 insertions(+), 7 deletions(-) diff --git a/openapi/functions/claimServer/claimServer.yml b/openapi/functions/claimServer/claimServer.yml index 3f0cbc6..c4997a1 100644 --- a/openapi/functions/claimServer/claimServer.yml +++ b/openapi/functions/claimServer/claimServer.yml @@ -5,6 +5,7 @@ post: 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 + - Server security: - bearerAuth: ['InitialAdmin'] requestBody: diff --git a/openapi/functions/createNewGame/createNewGame.yml b/openapi/functions/createNewGame/createNewGame.yml index a79b3c8..7c6da5f 100644 --- a/openapi/functions/createNewGame/createNewGame.yml +++ b/openapi/functions/createNewGame/createNewGame.yml @@ -5,6 +5,7 @@ post: 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 + - Game security: - bearerAuth: [] requestBody: diff --git a/openapi/functions/setClientPassword/setClientPassword.yml b/openapi/functions/setClientPassword/setClientPassword.yml index 5fc94b0..50b2156 100644 --- a/openapi/functions/setClientPassword/setClientPassword.yml +++ b/openapi/functions/setClientPassword/setClientPassword.yml @@ -5,6 +5,7 @@ post: 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 + - Server security: - bearerAuth: ['Administrator'] requestBody: diff --git a/openapi/openapi.yml b/openapi/openapi.yml index e877a7f..17d6c31 100644 --- a/openapi/openapi.yml +++ b/openapi/openapi.yml @@ -19,20 +19,20 @@ components: tags: - name: Setup - description: Authorization + description: Functions typically ran shortly after a Game Server starts up for the first time - name: Authorization - description: Authorization + description: Anything related to API or Server access - name: Server - description: Server Status + description: Anything related to managing or adjusting the Server - name: Game - description: Game Settings + description: Anything related to the game running on the Server - name: Saves - description: Saves + description: Individual Save related management - name: Sessions - description: Sessions + description: Save Sessions related management paths: - # --- Setup + # --- Initialization # ClaimServer '/api/v1/?function=ClaimServer':