update OpenAPI docs to OAuth

packages/backend/src/misc/api-permissions.ts

@@ -1,35 +1,38 @@
-export const kinds = [
-	'read:account',
-	'write:account',
-	'read:blocks',
-	'write:blocks',
-	'read:drive',
-	'write:drive',
-	'read:favorites',
-	'write:favorites',
-	'read:following',
-	'write:following',
-	'read:messaging',
-	'write:messaging',
-	'read:mutes',
-	'write:mutes',
-	'write:notes',
-	'read:notifications',
-	'write:notifications',
-	'read:reactions',
-	'write:reactions',
-	'write:votes',
-	'read:pages',
-	'write:pages',
-	'write:page-likes',
-	'read:page-likes',
-	'read:user-groups',
-	'write:user-groups',
-	'read:channels',
-	'write:channels',
-	'read:gallery',
-	'write:gallery',
-	'read:gallery-likes',
-	'write:gallery-likes',
-];
 // IF YOU ADD KINDS(PERMISSIONS), YOU MUST ADD TRANSLATIONS (under _permissions).
+
+// short English descriptions used for the documentation
+export const descriptions = {
+	'read:account': 'Read the accounts data.',
+	'write:account': 'Write the accounts data.',
+	'read:blocks': 'Read which users are blocked.',
+	'write:blocks': 'Create, change and delete blocks.',
+	'read:drive': 'List files and folders in the drive.',
+	'write:drive': 'Create, change and delete files from the drive.',
+	'read:favourites': 'List favourited notes.',
+	'write:favourites': 'Favourite or unfavourite notes.',
+	'read:following': 'Read who the user is following.',
+	'write:following': 'Follow or unfollow other users.',
+	'read:messaging': 'Read chat messages and history.',
+	'write:messaging': 'Create and delete chat messages.',
+	'read:mutes': 'List users which are muted or whose renotes are muted.',
+	'write:mutes': 'Create or delete (renote) mutes.',
+	'write:notes': 'Create or delete notes.',
+	'read:notifications': 'Read notifications.',
+	'write:notifications': 'Mark notifications as read or create notifications.',
+	'write:reactions': 'Create or delete reactions.',
+	'write:votes': 'Vote in polls.',
+	'read:pages': 'List and read pages.',
+	'write:pages': 'Create, modify and delete pages.',
+	'read:page-likes': 'List page likes.',
+	'write:page-likes': 'Like or unlike pages.',
+	'read:user-groups': 'List joined, owned and invited to groups.',
+	'write:user-groups': 'Create, modify, delete, transfer, join, or leave groups. Invite or ban others from groups. Accept or reject group invitations.',
+	'read:channels': 'List followed and owned channels.',
+	'write:channels': 'Create, modify, follow or unfollow channels.',
+	'read:gallery': 'Read gallery posts.',
+	'write:gallery': 'Create, modify or delete gallery posts.',
+	'read:gallery-likes': 'List which gallery posts are liked.',
+	'write:gallery-likes': 'Like or unlike gallery posts.',
+};
+
+export const kinds = Object.keys(descriptions);

packages/backend/src/server/api/openapi/gen-spec.ts

@@ -3,6 +3,7 @@ import { errors as errorDefinitions } from '../error.js';
 import endpoints from '../endpoints.js';
 import { schemas, convertSchemaToOpenApiSchema } from './schemas.js';
 import { httpCodes } from './http-codes.js';
+import { descriptions as scopes } from '@/misc/api-permissions.js';
 
 export function genOpenapiSpec() {
 	const spec = {
@@ -34,10 +35,15 @@ export function genOpenapiSpec() {
 					in: 'body',
 					name: 'i',
 				},
-				// TODO: change this to oauth2 when the remaining oauth stuff is set up
-				Bearer: {
-					type: 'http',
-					scheme: 'bearer',
+				OAuth: {
+					type: 'oauth2',
+					flows: {
+						authorizationCode: {
+							authorizationUrl: `${config.url}/auth`,
+							tokenUrl: `${config.apiUrl}/auth/session/oauth`,
+							scopes,
+						},
+					},
 				},
 			},
 		},
@@ -137,10 +143,16 @@ export function genOpenapiSpec() {
 			{
 				ApiKeyAuth: [],
 			},
-			{
-				Bearer: [],
-			},
 		];
+		if (endpoint.meta.kind) {
+			security.push({
+				OAuth: [endpoint.meta.kind],
+			});
+		} else {
+			security.push({
+				OAuth: [],
+			});
+		}
 		if (!endpoint.meta.requireCredential) {
 			// add this to make authentication optional
 			security.push({});