Merge pull request #10856 from nextcloud/openapi-update

Openapi update

lib/Controller/BotController.php

@@ -48,6 +48,7 @@
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\BruteForceProtection;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Utility\ITimeFactory;
@@ -140,6 +141,7 @@ protected function getBotFromHeaders(string $token, string $message): Bot {
 	 * 413: Message too long
 	 */
 	#[BruteForceProtection(action: 'bot')]
+	#[OpenAPI(scope: 'bots')]
 	#[PublicPage]
 	public function sendMessage(string $token, string $message, string $referenceId = '', int $replyTo = 0, bool $silent = false): DataResponse {
 		if (trim($message) === '') {
@@ -202,6 +204,7 @@ public function sendMessage(string $token, string $message, string $referenceId
 	 * 404: Reaction not found
 	 */
 	#[BruteForceProtection(action: 'bot')]
+	#[OpenAPI(scope: 'bots')]
 	#[PublicPage]
 	public function react(string $token, int $messageId, string $reaction): DataResponse {
 		try {
@@ -254,6 +257,7 @@ public function react(string $token, int $messageId, string $reaction): DataResp
 	 * 404: Reaction not found
 	 */
 	#[BruteForceProtection(action: 'bot')]
+	#[OpenAPI(scope: 'bots')]
 	#[PublicPage]
 	public function deleteReaction(string $token, int $messageId, string $reaction): DataResponse {
 		try {
@@ -297,6 +301,7 @@ public function deleteReaction(string $token, int $messageId, string $reaction):
 	 *
 	 * 200: Bot list returned
 	 */
+	#[OpenAPI(scope: OpenAPI::SCOPE_ADMINISTRATION, tags: ['settings'])]
 	public function adminListBots(): DataResponse {
 		$data = [];
 		$bots = $this->botServerMapper->getAllBots();

lib/Controller/CertificateController.php

@@ -28,6 +28,7 @@
 
 use OCA\Talk\Service\CertificateService;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\IL10N;
@@ -53,6 +54,7 @@ public function __construct(
 	 * 200: Certificate expiration returned
 	 * 400: Getting certificate expiration is not possible
 	 */
+	#[OpenAPI(scope: OpenAPI::SCOPE_ADMINISTRATION, tags: ['settings'])]
 	public function getCertificateExpiration(string $host): DataResponse {
 		try {
 			$expirationInDays = $this->certificateService->getCertificateExpirationInDays($host);

lib/Controller/CommandController.php

@@ -28,7 +28,7 @@
 
 use OCA\Talk\Model\Command;
 use OCA\Talk\Service\CommandService;
-use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\IRequest;
@@ -46,7 +46,7 @@ public function __construct(
 	/**
 	 * @deprecated Commands are deprecated in favor of Bots
 	 */
-	#[IgnoreOpenAPI]
+	#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 	public function index(): DataResponse {
 		$commands = $this->commandService->findAll();
 

lib/Controller/FederationController.php

@@ -35,8 +35,8 @@
 use OCA\Talk\ResponseDefinitions;
 use OCP\AppFramework\Db\MultipleObjectsReturnedException;
 use OCP\AppFramework\Http;
-use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\DB\Exception as DBException;
@@ -49,7 +49,7 @@
  *
  * @psalm-import-type TalkFederationInvite from ResponseDefinitions
  */
-#[IgnoreOpenAPI]
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class FederationController extends OCSController {
 
 	public function __construct(

lib/Controller/HostedSignalingServerController.php

@@ -32,7 +32,7 @@
 use OCA\Talk\Exceptions\HostedSignalingServerInputException;
 use OCA\Talk\Service\HostedSignalingServerService;
 use OCP\AppFramework\Http;
-use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
@@ -64,7 +64,7 @@ public function __construct(
 	 * 200: Authentication credentials returned
 	 * 412: Getting authentication credentials is not possible
 	 */
-	#[IgnoreOpenAPI]
+	#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 	#[PublicPage]
 	public function auth(): DataResponse {
 		$storedNonce = $this->config->getAppValue('spreed', 'hosted-signaling-server-nonce', '');

lib/Controller/MatterbridgeSettingsController.php

@@ -30,6 +30,7 @@
 use OCA\Talk\Exceptions\WrongPermissionsException;
 use OCA\Talk\MatterbridgeManager;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\IRequest;
@@ -52,6 +53,7 @@ public function __construct(
 	 * 200: Bridge version returned
 	 * 400: Getting bridge version is not possible
 	 */
+	#[OpenAPI(scope: OpenAPI::SCOPE_ADMINISTRATION, tags: ['matterbridge'])]
 	public function getMatterbridgeVersion(): DataResponse {
 		try {
 			$version = $this->bridgeManager->getCurrentVersionFromBinary();
@@ -79,6 +81,7 @@ public function getMatterbridgeVersion(): DataResponse {
 	 * 200: All bridges stopped successfully
 	 * 406: Stopping all bridges is not possible
 	 */
+	#[OpenAPI(scope: OpenAPI::SCOPE_ADMINISTRATION, tags: ['matterbridge'])]
 	public function stopAllBridges(): DataResponse {
 		try {
 			$success = $this->bridgeManager->stopAllBridges();

lib/Controller/PageController.php

@@ -42,8 +42,8 @@
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\BruteForceProtection;
-use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\Attribute\UseSession;
 use OCP\AppFramework\Http\ContentSecurityPolicy;
@@ -69,7 +69,7 @@
 use OCP\Security\Bruteforce\IThrottler;
 use Psr\Log\LoggerInterface;
 
-#[IgnoreOpenAPI]
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class PageController extends Controller {
 	use TInitialState;
 

lib/Controller/PublicShareAuthController.php

@@ -29,6 +29,7 @@
 use OCA\Talk\Room;
 use OCA\Talk\Service\RoomService;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
@@ -71,6 +72,7 @@ public function __construct(
 	 * 404: Share not found
 	 */
 	#[PublicPage]
+	#[OpenAPI(tags: ['files_integration'])]
 	public function createRoom(string $shareToken): DataResponse {
 		try {
 			$share = $this->shareManager->getShareByToken($shareToken);

lib/Controller/RecordingController.php

@@ -42,8 +42,8 @@
 use OCA\Talk\Service\RoomService;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\BruteForceProtection;
-use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\Http\Client\IClientService;
@@ -77,6 +77,7 @@ public function __construct(
 	 * 200: Welcome message returned
 	 * 404: Recording server not found or not configured
 	 */
+	#[OpenAPI(scope: OpenAPI::SCOPE_ADMINISTRATION, tags: ['settings'])]
 	public function getWelcomeMessage(int $serverId): DataResponse {
 		$recordingServers = $this->talkConfig->getRecordingServers();
 		if (empty($recordingServers) || !isset($recordingServers[$serverId])) {
@@ -175,7 +176,7 @@ protected function getInputStream(): string {
 	 * 403: Missing permissions to update recording status
 	 * 404: Room not found
 	 */
-	#[IgnoreOpenAPI]
+	#[OpenAPI(scope: 'backend-recording')]
 	#[PublicPage]
 	#[BruteForceProtection(action: 'talkRecordingSecret')]
 	public function backend(): DataResponse {
@@ -366,6 +367,7 @@ public function stop(): DataResponse {
 	 */
 	#[PublicPage]
 	#[BruteForceProtection(action: 'talkRecordingSecret')]
+	#[OpenAPI(scope: 'backend-recording')]
 	#[RequireRoom]
 	public function store(string $owner): DataResponse {
 		$data = $this->room->getToken();

lib/Controller/RoomController.php

@@ -66,8 +66,8 @@
 use OCP\App\IAppManager;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\BruteForceProtection;
-use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Utility\ITimeFactory;
@@ -311,6 +311,8 @@ public function getBreakoutRooms(): DataResponse {
 	#[BruteForceProtection(action: 'talkFederationAccess')]
 	#[BruteForceProtection(action: 'talkRoomToken')]
 	#[BruteForceProtection(action: 'talkSipBridgeSecret')]
+	#[OpenAPI]
+	#[OpenAPI(scope: 'backend-sipbridge')]
 	public function getSingleRoom(string $token): DataResponse {
 		try {
 			$isSIPBridgeRequest = $this->validateSIPBridgeRequest($token);
@@ -1528,9 +1530,9 @@ public function joinRoom(string $token, string $password = '', bool $force = tru
 	 * 404: Participant not found
 	 * 501: SIP dial-in is not configured
 	 */
-	#[IgnoreOpenAPI]
 	#[PublicPage]
 	#[BruteForceProtection(action: 'talkSipBridgeSecret')]
+	#[OpenAPI(scope: 'backend-sipbridge')]
 	#[RequireRoom]
 	public function verifyDialInPin(string $pin): DataResponse {
 		try {
@@ -1568,11 +1570,12 @@ public function verifyDialInPin(string $pin): DataResponse {
 	 *  200: Participant created successfully
 	 *  400: Phone number and details could not be confirmed
 	 *  401: SIP request invalid
+	 *  404: Phone number is not invited as a participant
 	 *  501: SIP dial-out is not configured
 	 */
-	#[IgnoreOpenAPI]
 	#[PublicPage]
 	#[BruteForceProtection(action: 'talkSipBridgeSecret')]
+	#[OpenAPI(scope: 'backend-sipbridge')]
 	#[RequireRoom]
 	public function verifyDialOutNumber(string $number, array $options = []): DataResponse {
 		try {
@@ -1617,9 +1620,9 @@ public function verifyDialOutNumber(string $number, array $options = []): DataRe
 	 * 400: SIP not enabled
 	 * 401: SIP request invalid
 	 */
-	#[IgnoreOpenAPI]
 	#[PublicPage]
 	#[BruteForceProtection(action: 'talkSipBridgeSecret')]
+	#[OpenAPI(scope: 'backend-sipbridge')]
 	#[RequireRoom]
 	public function createGuestByDialIn(): DataResponse {
 		try {
@@ -1656,9 +1659,9 @@ public function createGuestByDialIn(): DataResponse {
 	 * 404: Participant was not found
 	 * 501: SIP dial-out is not configured
 	 */
-	#[IgnoreOpenAPI]
 	#[PublicPage]
 	#[BruteForceProtection(action: 'talkSipBridgeSecret')]
+	#[OpenAPI(scope: 'backend-sipbridge')]
 	#[RequireRoom]
 	public function rejectedDialOutRequest(string $callId, array $options = []): DataResponse {
 		try {

lib/Controller/SettingsController.php

@@ -32,6 +32,7 @@
 use OCA\Talk\Service\ParticipantService;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\Files\Folder;
@@ -129,6 +130,7 @@ protected function validateUserSetting(string $setting, $value): bool {
 	 *
 	 * 200: Successfully set new SIP settings
 	 */
+	#[OpenAPI(scope: OpenAPI::SCOPE_ADMINISTRATION, tags: ['settings'])]
 	public function setSIPSettings(
 		array $sipGroups = [],
 		string $dialInInfo = '',

lib/Controller/SignalingController.php

@@ -45,7 +45,7 @@
 use OCA\Talk\TalkSession;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\BruteForceProtection;
-use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
@@ -129,6 +129,7 @@ private function validateRecordingBackendRequest(string $data): bool {
 	#[PublicPage]
 	#[BruteForceProtection(action: 'talkRoomToken')]
 	#[BruteForceProtection(action: 'talkRecordingSecret')]
+	#[OpenAPI(tags: ['internal_signaling', 'external_signaling'])]
 	public function getSettings(string $token = ''): DataResponse {
 		$isRecordingRequest = false;
 
@@ -226,6 +227,7 @@ public function getSettings(string $token = ''): DataResponse {
 	 * 200: Welcome message returned
 	 * 404: Signaling server not found
 	 */
+	#[OpenAPI(scope: OpenAPI::SCOPE_ADMINISTRATION, tags: ['settings'])]
 	public function getWelcomeMessage(int $serverId): DataResponse {
 		$signalingServers = $this->talkConfig->getSignalingServers();
 		if (empty($signalingServers) || !isset($signalingServers[$serverId])) {
@@ -313,6 +315,7 @@ public function getWelcomeMessage(int $serverId): DataResponse {
 	 * 400: Sending signaling message is not possible
 	 */
 	#[PublicPage]
+	#[OpenAPI(tags: ['internal_signaling'])]
 	public function sendMessages(string $token, string $messages): DataResponse {
 		if ($this->talkConfig->getSignalingMode() !== Config::SIGNALING_INTERNAL) {
 			return new DataResponse('Internal signaling disabled.', Http::STATUS_BAD_REQUEST);
@@ -364,6 +367,7 @@ public function sendMessages(string $token, string $messages): DataResponse {
 	 * 409: Session killed
 	 */
 	#[PublicPage]
+	#[OpenAPI(tags: ['internal_signaling'])]
 	public function pullMessages(string $token): DataResponse {
 		if ($this->talkConfig->getSignalingMode() !== Config::SIGNALING_INTERNAL) {
 			return new DataResponse('Internal signaling disabled.', Http::STATUS_BAD_REQUEST);
@@ -543,7 +547,7 @@ protected function getInputStream(): string {
 	 *
 	 * 200: Always, sorry about that
 	 */
-	#[IgnoreOpenAPI]
+	#[OpenAPI(scope: 'backend-signaling')]
 	#[PublicPage]
 	#[BruteForceProtection(action: 'talkSignalingSecret')]
 	public function backend(): DataResponse {

lib/Controller/TempAvatarController.php

@@ -30,6 +30,7 @@
 use OC\NotSquareException;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\IAvatarManager;
@@ -59,6 +60,7 @@ public function __construct(
 	 * 400: Uploading avatar is not possible
 	 */
 	#[NoAdminRequired]
+	#[OpenAPI(tags: ['user_avatar'])]
 	public function postAvatar(): DataResponse {
 		$files = $this->request->getUploadedFile('files');
 
@@ -133,6 +135,7 @@ public function postAvatar(): DataResponse {
 	 * 400: Deleting avatar is not possible
 	 */
 	#[NoAdminRequired]
+	#[OpenAPI(tags: ['user_avatar'])]
 	public function deleteAvatar(): DataResponse {
 		try {
 			$avatar = $this->avatarManager->getAvatar($this->userId);