enhance(backend): restore OpenAPI endpoints (#10281)

* enhance(backend): restore OpenAPI endpoints * Update CHANGELOG.md * version * set max-age * update redoc * follow redoc documentation --------- Co-authored-by: tamaina <tamaina@hotmail.co.jp>
2024-12-22 18:50:00 +00:00 · 2023-03-09 18:37:44 +01:00 · 2023-03-09 18:37:44 +01:00 · e0b7633a7a
commit e0b7633a7a
parent caf646fcb0
10 changed files with 270 additions and 29 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -2,10 +2,10 @@
 ## 13.x.x (unreleased)

 ### Improvements
- 
+-

 ### Bugfixes
- 
+-

 You should also include the user name that made the change.
 -->
@ -17,9 +17,11 @@ You should also include the user name that made the change.
 - ノートごとに絵文字リアクションを受け取るか設定できるように
 - enhance(client): DM作成時にメンションも含むように
 - enhance(client): フォロー申請のボタンのデザインを改善
+- enhance(backend): OpenAPIエンドポイントを復旧

 ### Bugfixes
 - ロールで広告を無効にするとadmin/adsでプレビューがでてこない問題を修正
+- /api-consoleページにアクセスすると404が出る問題を修正

 ## 13.9.2 (2023/03/06)

@ -257,8 +259,8 @@ You should also include the user name that made the change.
 ## 13.3.2 (2023/02/04)

 ### Improvements
- 外部メディアプロキシへの対応を強化しました  
-  外部メディアプロキシのFastify実装を作りました  
+- 外部メディアプロキシへの対応を強化しました
+  外部メディアプロキシのFastify実装を作りました
  https://github.com/misskey-dev/media-proxy
 - Server: improve performance

@ -421,7 +423,7 @@ You should also include the user name that made the change.
 	- ユーザーごとのドライブ容量設定はロールに統合されました。
 	- インスタンスデフォルトのドライブ容量設定はロールに統合されました。アップデート後、ベースロールもしくはコンディショナルロールでドライブ容量を編集してください。
 	- LTL/GTLの解放状態はロールに統合されました。
- Dockerの実行をrootで行わないようにしました。Dockerかつオブジェクトストレージを使用していない場合は`chown -hR 991.991 ./files`を実行してください。  
+- Dockerの実行をrootで行わないようにしました。Dockerかつオブジェクトストレージを使用していない場合は`chown -hR 991.991 ./files`を実行してください。
  https://github.com/misskey-dev/misskey/pull/9560

 #### For users
@ -649,7 +651,7 @@ You should also include the user name that made the change.
 ## 12.112.2 (2022/07/08)

 ### Bugfixes
- Fix Docker doesn't work @mei23  
+- Fix Docker doesn't work @mei23
  Still not working on arm64 environment. (See 12.112.0)

 ## 12.112.1 (2022/07/07)
@ -691,7 +693,7 @@ same as 12.112.0
 - Improve player detection in URL preview @mei23
 - Add Badge Image to Push Notification #8012 @tamaina
 - Server: Improve performance
- Server: Supports IPv6 on Redis transport. @mei23  
+- Server: Supports IPv6 on Redis transport. @mei23
  IPv4/IPv6 is used by default. You can tune this behavior via `redis.family`.
 - Server: Add possibility to log IP addresses of users @syuilo
 - Add additional drive capacity change support @CyberRex0
--- a/packages/backend/assets/redoc.html
+++ b/packages/backend/assets/redoc.html
@ -19,6 +19,6 @@
 	</head>
 	<body>
 		<redoc spec-url="/api.json" expand-responses="200" expand-single-schema-field="true"></redoc>
-		<script src="https://cdn.jsdelivr.net/npm/redoc@2.0.0-rc.50/bundles/redoc.standalone.js" integrity="sha256-WJbngBWN9vp6vkEuzeoSj5tE5saW9Hfj6/SinkzhL2s=" crossorigin="anonymous"></script>
+		<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
 	</body>
 </html>
--- a/packages/backend/src/server/FileServerService.ts
+++ b/packages/backend/src/server/FileServerService.ts
@ -2,7 +2,6 @@ import * as fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
 import { Inject, Injectable } from '@nestjs/common';
-import fastifyStatic from '@fastify/static';
 import rename from 'rename';
 import type { Config } from '@/config.js';
 import type { DriveFile, DriveFilesRepository } from '@/models/index.js';
@ -60,11 +59,6 @@ export class FileServerService {
 			done();
 		});

-		fastify.register(fastifyStatic, {
-			root: _dirname,
-			serve: false,
-		});
-
 		fastify.get('/files/app-default.jpg', (request, reply) => {
 			const file = fs.createReadStream(`${_dirname}/assets/dummy.png`);
 			reply.header('Content-Type', 'image/jpeg');
@ -311,20 +305,20 @@ export class FileServerService {
 					.linear(1.75, -(128 * 1.75) + 128) // 1.75x contrast
 					.flatten({ background: '#000' })
 					.toColorspace('b-w');
-	
+
 				const stats = await mask.clone().stats();
-	
+
 				if (stats.entropy < 0.1) {
 					// エントロピーがあまりない場合は404にする
 					throw new StatusError('Skip to provide badge', 404);
 				}
-	
+
 				const data = sharp({
 					create: { width: 96, height: 96, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
 				})
 					.pipelineColorspace('b-w')
 					.boolean(await mask.png().toBuffer(), 'eor');
-	
+
 				image = {
 					data: await data.png().toBuffer(),
 					ext: 'png',
@ -396,7 +390,7 @@ export class FileServerService {
 			const { filename } = await this.downloadService.downloadUrl(url, path);

 			const { mime, ext } = await this.fileInfoService.detectType(path);
-	
+
 			return {
 				state: 'remote',
 				mime, ext,
--- a/packages/backend/src/server/ServerModule.ts
+++ b/packages/backend/src/server/ServerModule.ts
@ -33,6 +33,7 @@ import { LocalTimelineChannelService } from './api/stream/channels/local-timelin
 import { QueueStatsChannelService } from './api/stream/channels/queue-stats.js';
 import { ServerStatsChannelService } from './api/stream/channels/server-stats.js';
 import { UserListChannelService } from './api/stream/channels/user-list.js';
+import { OpenApiServerService } from './api/openapi/OpenApiServerService.js';

@Module({
 	imports: [
@ -72,6 +73,7 @@ import { UserListChannelService } from './api/stream/channels/user-list.js';
 		QueueStatsChannelService,
 		ServerStatsChannelService,
 		UserListChannelService,
+		OpenApiServerService,
 	],
 	exports: [
 		ServerService,
--- a/packages/backend/src/server/ServerService.ts
+++ b/packages/backend/src/server/ServerService.ts
@ -1,7 +1,9 @@
 import cluster from 'node:cluster';
 import * as fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { Inject, Injectable, OnApplicationShutdown } from '@nestjs/common';
 import Fastify, { FastifyInstance } from 'fastify';
+import fastifyStatic from '@fastify/static';
 import { IsNull } from 'typeorm';
 import { GlobalEventService } from '@/core/GlobalEventService.js';
 import type { Config } from '@/config.js';
@ -21,6 +23,9 @@ import { StreamingApiServerService } from './api/StreamingApiServerService.js';
 import { WellKnownServerService } from './WellKnownServerService.js';
 import { FileServerService } from './FileServerService.js';
 import { ClientServerService } from './web/ClientServerService.js';
+import { OpenApiServerService } from './api/openapi/OpenApiServerService.js';
+
+const _dirname = fileURLToPath(new URL('.', import.meta.url));

@Injectable()
 export class ServerService implements OnApplicationShutdown {
@ -42,6 +47,7 @@ export class ServerService implements OnApplicationShutdown {

 		private userEntityService: UserEntityService,
 		private apiServerService: ApiServerService,
+		private openApiServerService: OpenApiServerService,
 		private streamingApiServerService: StreamingApiServerService,
 		private activityPubServerService: ActivityPubServerService,
 		private wellKnownServerService: WellKnownServerService,
@ -71,7 +77,15 @@ export class ServerService implements OnApplicationShutdown {
 			});
 		}

+		// Register non-serving static server so that the child services can use reply.sendFile.
+		// `root` here is just a placeholder and each call must use its own `rootPath`.
+		fastify.register(fastifyStatic, {
+			root: _dirname,
+			serve: false,
+		});
+
 		fastify.register(this.apiServerService.createServer, { prefix: '/api' });
+		fastify.register(this.openApiServerService.createServer);
 		fastify.register(this.fileServerService.createServer);
 		fastify.register(this.activityPubServerService.createServer);
 		fastify.register(this.nodeinfoServerService.createServer);
--- a/packages/backend/src/server/api/ApiServerService.ts
+++ b/packages/backend/src/server/api/ApiServerService.ts
@ -167,7 +167,7 @@ export class ApiServerService {
 		// Make sure any unknown path under /api returns HTTP 404 Not Found,
 		// because otherwise ClientServerService will return the base client HTML
 		// page with HTTP 200.
-		fastify.get('*', (request, reply) => {
+		fastify.get('/*', (request, reply) => {
 			reply.code(404);
 			// Mock ApiCallService.send's error handling
 			reply.send({
--- a/packages/backend/src/server/api/openapi/OpenApiServerService.ts
+++ b/packages/backend/src/server/api/openapi/OpenApiServerService.ts
@ -0,0 +1,31 @@
+import { fileURLToPath } from 'node:url';
+import { Inject, Injectable } from '@nestjs/common';
+import type { Config } from '@/config.js';
+import { DI } from '@/di-symbols.js';
+import { bindThis } from '@/decorators.js';
+import { genOpenapiSpec } from './gen-spec.js';
+import type { FastifyInstance, FastifyPluginOptions } from 'fastify';
+
+const staticAssets = fileURLToPath(new URL('../../../../assets/', import.meta.url));
+
+@Injectable()
+export class OpenApiServerService {
+	constructor(
+		@Inject(DI.config)
+		private config: Config,
+	) {
+	}
+
+	@bindThis
+	public createServer(fastify: FastifyInstance, _options: FastifyPluginOptions, done: (err?: Error) => void) {
+		fastify.get('/api-doc', async (_request, reply) => {
+			reply.header('Cache-Control', 'public, max-age=86400');
+			return await reply.sendFile('/redoc.html', staticAssets);
+		});
+		fastify.get('/api.json', (_request, reply) => {
+			reply.header('Cache-Control', 'public, max-age=600');
+			reply.send(genOpenapiSpec(this.config));
+		});
+		done();
+	}
+}
--- a/packages/backend/src/server/api/openapi/gen-spec.ts
+++ b/packages/backend/src/server/api/openapi/gen-spec.ts
@ -0,0 +1,193 @@
+import type { Config } from '@/config.js';
+import endpoints from '../endpoints.js';
+import { errors as basicErrors } from './errors.js';
+import { schemas, convertSchemaToOpenApiSchema } from './schemas.js';
+
+export function genOpenapiSpec(config: Config) {
+	const spec = {
+		openapi: '3.0.0',
+
+		info: {
+			version: config.version,
+			title: 'Misskey API',
+			'x-logo': { url: '/static-assets/api-doc.png' },
+		},
+
+		externalDocs: {
+			description: 'Repository',
+			url: 'https://github.com/misskey-dev/misskey',
+		},
+
+		servers: [{
+			url: config.apiUrl,
+		}],
+
+		paths: {} as any,
+
+		components: {
+			schemas: schemas,
+
+			securitySchemes: {
+				ApiKeyAuth: {
+					type: 'apiKey',
+					in: 'body',
+					name: 'i',
+				},
+			},
+		},
+	};
+
+	for (const endpoint of endpoints.filter(ep => !ep.meta.secure)) {
+		const errors = {} as any;
+
+		if (endpoint.meta.errors) {
+			for (const e of Object.values(endpoint.meta.errors)) {
+				errors[e.code] = {
+					value: {
+						error: e,
+					},
+				};
+			}
+		}
+
+		const resSchema = endpoint.meta.res ? convertSchemaToOpenApiSchema(endpoint.meta.res) : {};
+
+		let desc = (endpoint.meta.description ? endpoint.meta.description : 'No description provided.') + '\n\n';
+		desc += `**Credential required**: *${endpoint.meta.requireCredential ? 'Yes' : 'No'}*`;
+		if (endpoint.meta.kind) {
+			const kind = endpoint.meta.kind;
+			desc += ` / **Permission**: *${kind}*`;
+		}
+
+		const requestType = endpoint.meta.requireFile ? 'multipart/form-data' : 'application/json';
+		const schema = { ...endpoint.params };
+
+		if (endpoint.meta.requireFile) {
+			schema.properties = {
+				...schema.properties,
+				file: {
+					type: 'string',
+					format: 'binary',
+					description: 'The file contents.',
+				},
+			};
+			schema.required = [...schema.required ?? [], 'file'];
+		}
+
+		const info = {
+			operationId: endpoint.name,
+			summary: endpoint.name,
+			description: desc,
+			externalDocs: {
+				description: 'Source code',
+				url: `https://github.com/misskey-dev/misskey/blob/develop/packages/backend/src/server/api/endpoints/${endpoint.name}.ts`,
+			},
+			...(endpoint.meta.tags ? {
+				tags: [endpoint.meta.tags[0]],
+			} : {}),
+			...(endpoint.meta.requireCredential ? {
+				security: [{
+					ApiKeyAuth: [],
+				}],
+			} : {}),
+			requestBody: {
+				required: true,
+				content: {
+					[requestType]: {
+						schema,
+					},
+				},
+			},
+			responses: {
+				...(endpoint.meta.res ? {
+					'200': {
+						description: 'OK (with results)',
+						content: {
+							'application/json': {
+								schema: resSchema,
+							},
+						},
+					},
+				} : {
+					'204': {
+						description: 'OK (without any results)',
+					},
+				}),
+				'400': {
+					description: 'Client error',
+					content: {
+						'application/json': {
+							schema: {
+								$ref: '#/components/schemas/Error',
+							},
+							examples: { ...errors, ...basicErrors['400'] },
+						},
+					},
+				},
+				'401': {
+					description: 'Authentication error',
+					content: {
+						'application/json': {
+							schema: {
+								$ref: '#/components/schemas/Error',
+							},
+							examples: basicErrors['401'],
+						},
+					},
+				},
+				'403': {
+					description: 'Forbidden error',
+					content: {
+						'application/json': {
+							schema: {
+								$ref: '#/components/schemas/Error',
+							},
+							examples: basicErrors['403'],
+						},
+					},
+				},
+				'418': {
+					description: 'I\'m Ai',
+					content: {
+						'application/json': {
+							schema: {
+								$ref: '#/components/schemas/Error',
+							},
+							examples: basicErrors['418'],
+						},
+					},
+				},
+				...(endpoint.meta.limit ? {
+					'429': {
+						description: 'To many requests',
+						content: {
+							'application/json': {
+								schema: {
+									$ref: '#/components/schemas/Error',
+								},
+								examples: basicErrors['429'],
+							},
+						},
+					},
+				} : {}),
+				'500': {
+					description: 'Internal server error',
+					content: {
+						'application/json': {
+							schema: {
+								$ref: '#/components/schemas/Error',
+							},
+							examples: basicErrors['500'],
+						},
+					},
+				},
+			},
+		};
+
+		spec.paths['/' + endpoint.name] = {
+			post: info,
+		};
+	}
+
+	return spec;
+}
--- a/packages/backend/src/server/web/ClientServerService.ts
+++ b/packages/backend/src/server/web/ClientServerService.ts
@ -194,11 +194,6 @@ export class ClientServerService {

 		//#region static assets

-		fastify.register(fastifyStatic, {
-			root: _dirname,
-			serve: false,
-		});
-
 		fastify.register(fastifyStatic, {
 			root: staticAssets,
 			prefix: '/static-assets/',
--- a/packages/backend/test/e2e/fetch-resource.ts
+++ b/packages/backend/test/e2e/fetch-resource.ts
@ -13,6 +13,7 @@ const UNSPECIFIED = '*/*';
 // Response Content-Type
 const AP = 'application/activity+json; charset=utf-8';
 const HTML = 'text/html; charset=utf-8';
+const JSON_UTF8 = 'application/json; charset=utf-8';

 describe('Fetch resource', () => {
 	let p: INestApplicationContext;
@ -52,14 +53,17 @@ describe('Fetch resource', () => {
 			assert.strictEqual(res.type, HTML);
 		});

-		test('GET api-doc (廃止)', async () => {
+		test('GET api-doc', async () => {
 			const res = await simpleGet('/api-doc');
-			assert.strictEqual(res.status, 404);
+			assert.strictEqual(res.status, 200);
+			// fastify-static gives charset=UTF-8 instead of utf-8 and that's okay
+			assert.strictEqual(res.type?.toLowerCase(), HTML);
 		});

-		test('GET api.json (廃止)', async () => {
+		test('GET api.json', async () => {
 			const res = await simpleGet('/api.json');
-			assert.strictEqual(res.status, 404);
+			assert.strictEqual(res.status, 200);
+			assert.strictEqual(res.type, JSON_UTF8);
 		});

 		test('GET api/foo (存在しない)', async () => {
@ -68,6 +72,12 @@ describe('Fetch resource', () => {
 			assert.strictEqual(res.body.error.code, 'UNKNOWN_API_ENDPOINT');
 		});

+		test('GET api-console (client page)', async () => {
+			const res = await simpleGet('/api-console');
+			assert.strictEqual(res.status, 200);
+			assert.strictEqual(res.type, HTML);
+		});
+
 		test('GET favicon.ico', async () => {
 			const res = await simpleGet('/favicon.ico');
 			assert.strictEqual(res.status, 200);