chore(api): add OpenAPI yaml export

apps/api/package.json

@@ -7,6 +7,7 @@
   "scripts": {
     "start": "node --enable-source-maps .",
     "build": "swc src  --config-file ../../.swcrc --out-dir dist --strip-leading-paths",
+    "openapi:generate": "pnpm --filter @statsify/util build && pnpm --filter @statsify/logger build && pnpm --filter @statsify/math build && pnpm --filter @statsify/schemas build && pnpm --filter @statsify/assets build && pnpm --filter @statsify/rendering build && pnpm --filter @statsify/api-client build && pnpm build && node dist/openapi.js",
     "test:types": "tsc --noEmit",
     "lint": "eslint"
   },
@@ -42,6 +43,7 @@
     "toad-scheduler": "^3.0.1"
   },
   "devDependencies": {
+    "js-yaml": "^4.1.0",
     "@nestjs/testing": "^11.1.6",
     "@types/luxon": "^3.4.2"
   },
@@ -99,4 +101,4 @@
       "default": "./dist/redis/index.js"
     }
   }
-}
+}

apps/api/src/app.module.ts

@@ -20,8 +20,16 @@ import { TypegooseModule } from "@m8a/nestjs-typegoose";
 import { UserModule } from "#user";
 import { config } from "@statsify/util";
 
-const mongoUri = await config("database.mongoUri");
-const redisUrl = await config("database.redisUrl");
+const isOpenApiGeneration = process.env.STATSIFY_OPENAPI_GENERATE === "1";
+
+const mongoUri = await config(
+  "database.mongoUri",
+  isOpenApiGeneration ? { default: "mongodb://127.0.0.1:27017/statsify-openapi" } : {}
+);
+const redisUrl = await config(
+  "database.redisUrl",
+  isOpenApiGeneration ? { default: "redis://127.0.0.1:6379" } : {}
+);
 
 @Module({
   imports: [

apps/api/src/auth/auth.controller.ts

@@ -12,7 +12,7 @@ import { Auth } from "./auth.decorator.js";
 import { AuthRole } from "./auth.role.js";
 import { AuthService } from "./auth.service.js";
 import { Body, Controller, Get, Headers, Post, Query } from "@nestjs/common";
-import { GetKeyResponse } from "@statsify/api-client";
+import { GetKeyResponse } from "@statsify/api-client/responses";
 
 @Controller("/auth")
 export class AuthController {

apps/api/src/dtos/cache.dto.ts

@@ -7,7 +7,7 @@
  */
 
 import { ApiProperty } from "@nestjs/swagger";
-import { CacheLevel } from "@statsify/api-client";
+import { CacheLevel } from "@statsify/api-client/constants";
 import { IsEnum, IsOptional } from "class-validator";
 
 export class CacheDto {

apps/api/src/dtos/guild.dto.ts

@@ -8,7 +8,7 @@
 
 import { ApiProperty } from "@nestjs/swagger";
 import { CacheDto } from "./cache.dto.js";
-import { GuildQuery } from "@statsify/api-client";
+import { GuildQuery } from "@statsify/api-client/constants";
 import { IsEnum, IsString, MaxLength, MinLength } from "class-validator";
 
 export class GuildDto extends CacheDto {

apps/api/src/guild/guild.controller.ts

@@ -18,10 +18,12 @@ import { Controller, Get, Query } from "@nestjs/common";
 import {
   ErrorResponse,
   GetGuildResponse,
+} from "@statsify/api-client/responses";
+import { GuildDto } from "#dtos";
+import {
   GuildNotFoundException,
   PlayerNotFoundException,
-} from "@statsify/api-client";
-import { GuildDto } from "#dtos";
+} from "@statsify/api-client/exceptions";
 import { GuildService } from "./guild.service.js";
 
 @Controller("/guild")

apps/api/src/guild/guild.service.ts

@@ -8,12 +8,14 @@
 
 import {
   CacheLevel,
-  GuildNotFoundException,
   GuildQuery,
-  PlayerNotFoundException,
-} from "@statsify/api-client";
+} from "@statsify/api-client/constants";
 import { Guild, GuildMember, Player, deserialize, serialize } from "@statsify/schemas";
 import { GuildLeaderboardService } from "./leaderboards/guild-leaderboard.service.js";
+import {
+  GuildNotFoundException,
+  PlayerNotFoundException,
+} from "@statsify/api-client/exceptions";
 import { HypixelService } from "#hypixel";
 import { InjectModel } from "@m8a/nestjs-typegoose";
 import { Injectable } from "@nestjs/common";

apps/api/src/guild/leaderboards/guild-leaderboard.controller.ts

@@ -11,13 +11,13 @@ import { Auth } from "#auth";
 import { Body, Controller, Post } from "@nestjs/common";
 import {
   ErrorResponse,
-  LeaderboardQuery,
   PostLeaderboardRankingsResponse,
   PostLeaderboardResponse,
-} from "@statsify/api-client";
+} from "@statsify/api-client/responses";
 import { Guild } from "@statsify/schemas";
 import { GuildLeaderboardDto, GuildRankingDto } from "#dtos";
 import { GuildLeaderboardService } from "./guild-leaderboard.service.js";
+import { LeaderboardQuery } from "@statsify/api-client/constants";
 
 @Controller("/guild/leaderboards")
 export class GuildLeaderboardController {

apps/api/src/guild/leaderboards/guild-leaderboard.service.ts

@@ -6,8 +6,9 @@
  * https://github.com/Statsify/statsify/blob/main/LICENSE
  */
 
-import { GUILD_ID_REGEX, GuildNotFoundException } from "@statsify/api-client";
+import { GUILD_ID_REGEX } from "@statsify/api-client/constants";
 import { Guild } from "@statsify/schemas";
+import { GuildNotFoundException } from "@statsify/api-client/exceptions";
 import { InjectModel } from "@m8a/nestjs-typegoose";
 import { InjectRedis } from "#redis";
 import { Injectable } from "@nestjs/common";

apps/api/src/hypixel-resources/hypixel-resources.controller.ts

@@ -18,7 +18,7 @@ import {
   ErrorResponse,
   GetGamecountsResponse,
   GetWatchdogResponse,
-} from "@statsify/api-client";
+} from "@statsify/api-client/responses";
 import { HypixelService } from "#hypixel";
 
 @Controller("/hypixelresources")

apps/api/src/hypixel/hypixel.module.ts

@@ -11,12 +11,17 @@ import { HypixelService } from "./hypixel.service.js";
 import { Module } from "@nestjs/common";
 import { config } from "@statsify/util";
 
+const isOpenApiGeneration = process.env.STATSIFY_OPENAPI_GENERATE === "1";
+
 @Module({
   imports: [
     HttpModule.register({
       baseURL: "https://api.hypixel.net/",
       headers: {
-        "API-Key": await config("hypixelApi.key"),
+        "API-Key": await config(
+          "hypixelApi.key",
+          isOpenApiGeneration ? { default: "" } : {}
+        ),
         "accept-encoding": "*",
       },
       timeout: await config("hypixelApi.timeout", { default: 5000 }),

apps/api/src/hypixel/hypixel.service.ts

@@ -7,7 +7,7 @@
  */
 
 import * as Sentry from "@sentry/node";
-import { CacheLevel } from "@statsify/api-client";
+import { CacheLevel } from "@statsify/api-client/constants";
 import {
   GameCounts,
   Guild,

apps/api/src/index.ts

@@ -8,16 +8,16 @@
 
 import * as Sentry from "@sentry/node";
 import handlebars from "handlebars";
-import packageJson from "../package.json" with { type: "json" };
 import { AppModule } from "./app.module.js";
-import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
 import { FastifyAdapter, NestFastifyApplication } from "@nestjs/platform-fastify";
 import { Logger } from "@statsify/logger";
 import { NestFactory } from "@nestjs/core";
 import { SentryInterceptor } from "./sentry/index.js";
 import { Severity, setGlobalOptions } from "@typegoose/typegoose";
+import { SwaggerModule } from "@nestjs/swagger";
 import { ValidationPipe } from "@nestjs/common";
 import { config } from "@statsify/util";
+import { createSwaggerDocument } from "./swagger.js";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { mkdir } from "node:fs/promises";
@@ -75,26 +75,13 @@ app.useGlobalPipes(new ValidationPipe({ transform: true }));
 app.useGlobalInterceptors(new SentryInterceptor());
 
 // Swagger/Redoc docs
-const redoc = new DocumentBuilder()
-  .setTitle("Statsify API")
-  .setVersion(packageJson.version)
-  .setDescription(
-    "# Introduction\nThis is the official Statsify API documentation. [Website](https://statsify.net/) - [GitHub](https://github.com/Statsify/statsify)\n# Authentication\n\n<!-- ReDoc-Inject: <security-definitions> -->"
-  )
-  .addSecurity("ApiKey", {
-    type: "apiKey",
-    in: "header",
-    name: "x-api-key",
-  })
-  .build();
-
 // Fastify template renderer for Redoc
 app.setViewEngine({
   engine: { handlebars },
   templates: join(__dirname, "..", "views"),
 });
 
-const document = SwaggerModule.createDocument(app, redoc);
+const document = createSwaggerDocument(app);
 
 SwaggerModule.setup("swagger", app, document);
 

apps/api/src/js-yaml.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Statsify
+ *
+ * This source code is licensed under the GNU GPL v3 license found in the
+ * LICENSE file in the root directory of this source tree.
+ * https://github.com/Statsify/statsify/blob/main/LICENSE
+ */
+
+declare module "js-yaml" {
+  export function dump(
+    object: unknown,
+    options?: {
+      lineWidth?: number;
+      noRefs?: boolean;
+    }
+  ): string;
+}

apps/api/src/leaderboards/leaderboard.service.ts

@@ -12,7 +12,7 @@ import { DateTime } from "luxon";
 import { InjectRedis } from "#redis";
 import { Injectable, InternalServerErrorException } from "@nestjs/common";
 import { LeaderboardEnabledMetadata, LeaderboardScanner } from "@statsify/schemas";
-import { LeaderboardQuery } from "@statsify/api-client";
+import { LeaderboardQuery } from "@statsify/api-client/constants";
 import { Redis } from "ioredis";
 
 const DAYS_IN_WEEK = {

apps/api/src/openapi.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) Statsify
+ *
+ * This source code is licensed under the GNU GPL v3 license found in the
+ * LICENSE file in the root directory of this source tree.
+ * https://github.com/Statsify/statsify/blob/main/LICENSE
+ */
+
+import { FastifyAdapter, NestFastifyApplication } from "@nestjs/platform-fastify";
+import { NestFactory } from "@nestjs/core";
+import { Severity, setGlobalOptions } from "@typegoose/typegoose";
+import { ValidationPipe } from "@nestjs/common";
+import { config } from "@statsify/util";
+import { createSwaggerDocument } from "./swagger.js";
+import { dirname, join } from "node:path";
+import { dump } from "js-yaml";
+import { fileURLToPath } from "node:url";
+import { mkdir, writeFile } from "node:fs/promises";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+process.env.STATSIFY_OPENAPI_GENERATE = "1";
+process.env.VITEST ??= "1";
+
+process.on("uncaughtException", console.error);
+process.on("unhandledRejection", console.error);
+
+const mediaRoot = await config("api.mediaRoot", { default: "/tmp/statsify-openapi" });
+
+await mkdir(join(mediaRoot, "badges"), { recursive: true });
+
+setGlobalOptions({
+  options: { allowMixed: Severity.ALLOW },
+  schemaOptions: { _id: false },
+});
+
+const adapter = new FastifyAdapter({ bodyLimit: 5e6 });
+
+adapter
+  .getInstance()
+  .addContentTypeParser("image/png", { parseAs: "buffer" }, (_, body, done) =>
+    done(null, body)
+  );
+
+const { AppModule } = await import("./app.module.js");
+
+const app = await NestFactory.create<NestFastifyApplication>(AppModule, adapter, {
+  logger: false,
+});
+
+app.useGlobalPipes(new ValidationPipe({ transform: true }));
+
+const document = createSwaggerDocument(app);
+const outputPath = join(__dirname, "..", "..", "..", "statsify.openapi.yaml");
+
+await writeFile(outputPath, dump(document, { noRefs: true, lineWidth: 120 }));
+void app.close();
+process.exit(0);

apps/api/src/player/leaderboards/player-leaderboard.controller.ts

@@ -16,10 +16,10 @@ import { Auth } from "#auth";
 import { Body, Controller, Post } from "@nestjs/common";
 import {
   ErrorResponse,
-  LeaderboardQuery,
   PostLeaderboardRankingsResponse,
   PostLeaderboardResponse,
-} from "@statsify/api-client";
+} from "@statsify/api-client/responses";
+import { LeaderboardQuery } from "@statsify/api-client/constants";
 import { Player } from "@statsify/schemas";
 import { PlayerLeaderboardDto, PlayerRankingsDto } from "#dtos";
 import { PlayerLeaderboardService } from "./player-leaderboard.service.js";