First pass at generating API docs

beabee-communityrm · Jan 19, 2024 · abf3113 · abf3113
1 parent 9a0b924
commit abf3113
Show file tree

Hide file tree

Showing 34 changed files with 395 additions and 120 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -45,6 +45,7 @@
     "chance": "^1.1.11",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.0",
+    "class-validator-jsonschema": "^4.0.0",
     "clean-deep": "^3.4.0",
     "connect-busboy": "^1.0.0",
     "connect-pg-simple": "^9.0.1",
@@ -81,6 +82,7 @@
     "query-string": "^7.1.3",
     "reflect-metadata": "^0.1.13",
     "routing-controllers": "^0.10.4",
+    "routing-controllers-openapi": "^4.0.0",
     "slugify": "^1.6.6",
     "stripe": "^9.16.0",
     "tar-stream": "^3.1.6",

diff --git a/src/api/app.ts b/src/api/app.ts
@@ -12,22 +12,7 @@ import {
   useExpressServer
 } from "routing-controllers";
 
-import { ApiKeyController } from "./controllers/ApiKeyController";
-import { AuthController } from "./controllers/AuthController";
-import { CalloutController } from "./controllers/CalloutController";
-import { CalloutResponseController } from "./controllers/CalloutResponseController";
-import { CalloutResponseCommentController } from "./controllers/CalloutResponseCommentController";
-import { ContentController } from "./controllers/ContentController";
-import { EmailController } from "./controllers/EmailController";
-import { ContactController } from "./controllers/ContactController";
-import { NoticeController } from "./controllers/NoticeController";
-import { PaymentController } from "./controllers/PaymentController";
-import { SegmentController } from "./controllers/SegmentController";
-import { SignupController } from "./controllers/SignupController";
-import { StatsController } from "./controllers/StatsController";
-import { ResetPasswordController } from "./controllers/ResetPasswordController";
-import { ResetDeviceController } from "./controllers/ResetDeviceController";
-import { UploadController } from "./controllers/UploadController";
+import controllers from "@api/controllers";
 
 import { ValidateResponseInterceptor } from "./interceptors/ValidateResponseInterceptor";
 
@@ -72,24 +57,7 @@ initApp()
 
     useExpressServer(app, {
       routePrefix: "/1.0",
-      controllers: [
-        ApiKeyController,
-        AuthController,
-        CalloutController,
-        CalloutResponseController,
-        CalloutResponseCommentController,
-        ContentController,
-        EmailController,
-        ContactController,
-        NoticeController,
-        PaymentController,
-        SegmentController,
-        SignupController,
-        StatsController,
-        ResetPasswordController,
-        ResetDeviceController,
-        UploadController
-      ],
+      controllers,
       interceptors: [ValidateResponseInterceptor],
       middlewares: [AuthMiddleware],
       currentUserChecker,

diff --git a/src/api/controllers/ApiKeyController.ts b/src/api/controllers/ApiKeyController.ts
@@ -12,6 +12,7 @@ import {
   Delete,
   Param
 } from "routing-controllers";
+import { OpenAPI, ResponseSchema } from "routing-controllers-openapi";
 
 import { getRepository } from "@core/database";
 import { generateApiKey } from "@core/utils/auth";
@@ -24,26 +25,29 @@ import { CurrentAuth } from "@api/decorators/CurrentAuth";
 import {
   CreateApiKeyDto,
   GetApiKeyDto,
+  GetApiKeysListDto,
   ListApiKeysDto,
   NewApiKeyDto
 } from "@api/dto/ApiKeyDto";
-import { PaginatedDto } from "@api/dto/PaginatedDto";
 import ApiKeyTransformer from "@api/transformers/ApiKeyTransformer";
 
 import { AuthInfo } from "@type/auth-info";
 
+@OpenAPI({ tags: ["API Keys"] })
 @JsonController("/api-key")
 @Authorized("admin")
 export class ApiKeyController {
   @Get("/")
+  @ResponseSchema(GetApiKeysListDto)
   async getApiKeys(
     @CurrentAuth({ required: true }) auth: AuthInfo,
     @QueryParams() query: ListApiKeysDto
-  ): Promise<PaginatedDto<GetApiKeyDto>> {
+  ): Promise<GetApiKeysListDto> {
     return await ApiKeyTransformer.fetch(auth, query);
   }
 
   @Get("/:id")
+  @ResponseSchema(GetApiKeyDto, { statusCode: 200 })
   async getApiKey(
     @CurrentAuth({ required: true }) auth: AuthInfo,
     @Param("id") id: string
@@ -52,6 +56,7 @@ export class ApiKeyController {
   }
 
   @Post("/")
+  @ResponseSchema(NewApiKeyDto)
   async createApiKey(
     @CurrentAuth({ required: true }) auth: AuthInfo,
     @CurrentUser({ required: true }) creator: Contact,

diff --git a/src/api/controllers/CalloutController.ts b/src/api/controllers/CalloutController.ts
@@ -16,6 +16,7 @@ import {
   QueryParams,
   Res
 } from "routing-controllers";
+import { ResponseSchema } from "routing-controllers-openapi";
 import slugify from "slugify";
 import { QueryDeepPartialEntity } from "typeorm/query-builder/QueryPartialEntity";
 
@@ -30,17 +31,18 @@ import { GetExportQuery } from "@api/dto/BaseDto";
 import {
   CreateCalloutDto,
   GetCalloutDto,
+  GetCalloutListDto,
   GetCalloutOptsDto,
   ListCalloutsDto
 } from "@api/dto/CalloutDto";
 import {
   CreateCalloutResponseDto,
-  GetCalloutResponseDto,
+  GetCalloutResponseListDto,
   GetCalloutResponseMapDto,
+  GetCalloutResponseMapListDto,
   ListCalloutResponsesDto
 } from "@api/dto/CalloutResponseDto";
 import { CreateCalloutTagDto, GetCalloutTagDto } from "@api/dto/CalloutTagDto";
-import { PaginatedDto } from "@api/dto/PaginatedDto";
 
 import { CurrentAuth } from "@api/decorators/CurrentAuth";
 import PartialBody from "@api/decorators/PartialBody";
@@ -63,15 +65,17 @@ import { AuthInfo } from "@type/auth-info";
 @JsonController("/callout")
 export class CalloutController {
   @Get("/")
+  @ResponseSchema(GetCalloutListDto)
   async getCallouts(
     @CurrentAuth() auth: AuthInfo | undefined,
     @QueryParams() query: ListCalloutsDto
-  ): Promise<PaginatedDto<GetCalloutDto>> {
+  ): Promise<GetCalloutListDto> {
     return CalloutTransformer.fetch(auth, query);
   }
 
   @Authorized("admin")
   @Post("/")
+  @ResponseSchema(GetCalloutDto)
   async createCallout(@Body() data: CreateCalloutDto): Promise<GetCalloutDto> {
     const callout = await CalloutsService.createCallout(
       {
@@ -84,6 +88,7 @@ export class CalloutController {
   }
 
   @Get("/:slug")
+  @ResponseSchema(GetCalloutDto, { statusCode: 200 })
   async getCallout(
     @CurrentAuth() auth: AuthInfo | undefined,
     @Param("slug") slug: string,
@@ -97,6 +102,7 @@ export class CalloutController {
 
   @Authorized("admin")
   @Patch("/:slug")
+  @ResponseSchema(GetCalloutDto, { statusCode: 200 })
   async updateCallout(
     @CurrentAuth({ required: true }) auth: AuthInfo,
     @Param("slug") slug: string,
@@ -143,11 +149,12 @@ export class CalloutController {
   }
 
   @Get("/:slug/responses")
+  @ResponseSchema(GetCalloutResponseListDto)
   async getCalloutResponses(
     @CurrentAuth({ required: true }) auth: AuthInfo,
     @Param("slug") slug: string,
     @QueryParams() query: ListCalloutResponsesDto
-  ): Promise<PaginatedDto<GetCalloutResponseDto>> {
+  ): Promise<GetCalloutResponseListDto> {
     return await CalloutResponseTransformer.fetchForCallout(auth, slug, query);
   }
 
@@ -168,11 +175,12 @@ export class CalloutController {
   }
 
   @Get("/:slug/responses/map")
+  @ResponseSchema(GetCalloutResponseMapListDto)
   async getCalloutResponsesMap(
     @CurrentAuth() auth: AuthInfo | undefined,
     @Param("slug") slug: string,
     @QueryParams() query: ListCalloutResponsesDto
-  ): Promise<PaginatedDto<GetCalloutResponseMapDto>> {
+  ): Promise<GetCalloutResponseMapListDto> {
     return await CalloutResponseMapTransformer.fetchForCallout(
       auth,
       slug,
@@ -211,6 +219,7 @@ export class CalloutController {
 
   @Authorized("admin")
   @Get("/:slug/tags")
+  @ResponseSchema(GetCalloutTagDto, { isArray: true })
   async getCalloutTags(
     @CurrentAuth({ required: true }) auth: AuthInfo,
     @Param("slug") slug: string
@@ -227,6 +236,7 @@ export class CalloutController {
 
   @Authorized("admin")
   @Post("/:slug/tags")
+  @ResponseSchema(GetCalloutTagDto)
   async createCalloutTag(
     @Param("slug") slug: string,
     @Body() data: CreateCalloutTagDto
@@ -243,6 +253,7 @@ export class CalloutController {
 
   @Authorized("admin")
   @Get("/:slug/tags/:tag")
+  @ResponseSchema(GetCalloutTagDto, { statusCode: 200 })
   async getCalloutTag(
     @CurrentAuth({ required: true }) auth: AuthInfo,
     @Param("tag") tagId: string
@@ -252,6 +263,7 @@ export class CalloutController {
 
   @Authorized("admin")
   @Patch("/:slug/tags/:tag")
+  @ResponseSchema(GetCalloutTagDto, { statusCode: 200 })
   async updateCalloutTag(
     @CurrentAuth({ required: true }) auth: AuthInfo,
     @Param("slug") slug: string,