From ddfe8bb48e7eefab41e9a7fe39795a7539b18966 Mon Sep 17 00:00:00 2001 From: Laura Hausmann Date: Tue, 12 Dec 2023 18:34:24 +0100 Subject: [PATCH] [backend/web-api] Add OpenAPI descriptions and fix controller naming --- .pnp.cjs | 16 ++++++++-------- ...a-openapi-npm-2.2.0-b79af14354-a7ff2c0b1a.zip | 3 --- ...a-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip | 3 +++ package.json | 6 ++++++ packages/backend/package.json | 2 +- .../src/server/api/web/controllers/auth.ts | 4 +++- .../src/server/api/web/controllers/note.ts | 3 ++- .../src/server/api/web/controllers/timeline.ts | 3 ++- .../src/server/api/web/controllers/user.ts | 4 +++- yarn.lock | 14 +++++++++----- 10 files changed, 37 insertions(+), 21 deletions(-) delete mode 100644 .yarn/cache/@iceshrimp-koa-openapi-npm-2.2.0-b79af14354-a7ff2c0b1a.zip create mode 100644 .yarn/cache/@iceshrimp-koa-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip diff --git a/.pnp.cjs b/.pnp.cjs index 4ee1f8c70..b6245c655 100755 --- a/.pnp.cjs +++ b/.pnp.cjs @@ -1898,10 +1898,10 @@ const RAW_RUNTIME_STATE = }]\ ]],\ ["@iceshrimp/koa-openapi", [\ - ["npm:2.2.0::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.2.0%2Fkoa-openapi-2.2.0.tgz", {\ - "packageLocation": "./.yarn/cache/@iceshrimp-koa-openapi-npm-2.2.0-b79af14354-a7ff2c0b1a.zip/node_modules/@iceshrimp/koa-openapi/",\ + ["npm:2.4.1::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.4.1%2Fkoa-openapi-2.4.1.tgz", {\ + "packageLocation": "./.yarn/cache/@iceshrimp-koa-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip/node_modules/@iceshrimp/koa-openapi/",\ "packageDependencies": [\ - ["@iceshrimp/koa-openapi", "npm:2.2.0::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.2.0%2Fkoa-openapi-2.2.0.tgz"],\ + ["@iceshrimp/koa-openapi", "npm:2.4.1::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.4.1%2Fkoa-openapi-2.4.1.tgz"],\ ["@hapi/boom", "npm:10.0.1"],\ ["@koa/cors", "npm:4.0.0"],\ ["@koa/router", "npm:12.0.1"],\ @@ -1911,7 +1911,7 @@ const RAW_RUNTIME_STATE = ["koa", "npm:2.14.2"],\ ["koa-body", "npm:6.0.1"],\ ["koa-helmet", "npm:7.0.2"],\ - ["koa2-swagger-ui", "virtual:b79af143542f14e992898e20a1ab22405dbd6893d6a8c813e877de0a455aadcaf1a4faf2f8bc74ede210c0399435357919d77dcd4e83ecce226e0faf31581e3e#npm:5.10.0"],\ + ["koa2-swagger-ui", "virtual:8c7362549be2320b14415acd0a28c20c4a28a61f50998f521c19c171b924639d2efda4597f82a25044828aebf1f59af528473f27cfbb1764bf584786860b172c#npm:5.10.0"],\ ["lodash", "npm:4.17.21"],\ ["openapi-types", "npm:12.1.3"],\ ["reflect-metadata", "npm:0.1.13"]\ @@ -7217,7 +7217,7 @@ const RAW_RUNTIME_STATE = ["@bull-board/ui", "npm:5.6.0"],\ ["@discordapp/twemoji", "npm:14.1.2"],\ ["@hapi/boom", "npm:10.0.1"],\ - ["@iceshrimp/koa-openapi", "npm:2.2.0::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.2.0%2Fkoa-openapi-2.2.0.tgz"],\ + ["@iceshrimp/koa-openapi", "npm:2.4.1::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.4.1%2Fkoa-openapi-2.4.1.tgz"],\ ["@koa/cors", "npm:3.4.3"],\ ["@koa/multer", "virtual:aa59773ac87791c4813d53447077fcf8a847d6de5a301d34dc31286584b1dbb26d30d3adb5b4c41c1e8aea04371e926fda05c09c6253647c432e11d872a304ba#npm:3.0.2"],\ ["@koa/router", "npm:9.0.1"],\ @@ -17145,10 +17145,10 @@ const RAW_RUNTIME_STATE = ],\ "linkType": "SOFT"\ }],\ - ["virtual:b79af143542f14e992898e20a1ab22405dbd6893d6a8c813e877de0a455aadcaf1a4faf2f8bc74ede210c0399435357919d77dcd4e83ecce226e0faf31581e3e#npm:5.10.0", {\ - "packageLocation": "./.yarn/__virtual__/koa2-swagger-ui-virtual-7468e59b3e/0/cache/koa2-swagger-ui-npm-5.10.0-54bce94261-40575d377d.zip/node_modules/koa2-swagger-ui/",\ + ["virtual:8c7362549be2320b14415acd0a28c20c4a28a61f50998f521c19c171b924639d2efda4597f82a25044828aebf1f59af528473f27cfbb1764bf584786860b172c#npm:5.10.0", {\ + "packageLocation": "./.yarn/__virtual__/koa2-swagger-ui-virtual-d32ac78ca4/0/cache/koa2-swagger-ui-npm-5.10.0-54bce94261-40575d377d.zip/node_modules/koa2-swagger-ui/",\ "packageDependencies": [\ - ["koa2-swagger-ui", "virtual:b79af143542f14e992898e20a1ab22405dbd6893d6a8c813e877de0a455aadcaf1a4faf2f8bc74ede210c0399435357919d77dcd4e83ecce226e0faf31581e3e#npm:5.10.0"],\ + ["koa2-swagger-ui", "virtual:8c7362549be2320b14415acd0a28c20c4a28a61f50998f521c19c171b924639d2efda4597f82a25044828aebf1f59af528473f27cfbb1764bf584786860b172c#npm:5.10.0"],\ ["@types/koa", null],\ ["handlebars", "npm:4.7.8"],\ ["lodash", "npm:4.17.21"],\ diff --git a/.yarn/cache/@iceshrimp-koa-openapi-npm-2.2.0-b79af14354-a7ff2c0b1a.zip b/.yarn/cache/@iceshrimp-koa-openapi-npm-2.2.0-b79af14354-a7ff2c0b1a.zip deleted file mode 100644 index 9dd46a278..000000000 --- a/.yarn/cache/@iceshrimp-koa-openapi-npm-2.2.0-b79af14354-a7ff2c0b1a.zip +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:cbce7314ef75227caeac016c06f2282916ab5d5754c825a8f595c1e407dab52c -size 100168 diff --git a/.yarn/cache/@iceshrimp-koa-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip b/.yarn/cache/@iceshrimp-koa-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip new file mode 100644 index 000000000..a483d88fd --- /dev/null +++ b/.yarn/cache/@iceshrimp-koa-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:baf88bc93a6338fe4193fcaff6a1353ff3801370029d44ad916eaf9f09301670 +size 101881 diff --git a/package.json b/package.json index 7477b8ca1..9510cc0fd 100644 --- a/package.json +++ b/package.json @@ -76,6 +76,12 @@ "dependenciesMeta": { "@discordapp/twemoji@14.1.2": { "unplugged": true + }, + "@iceshrimp/koa-openapi@2.3.0": { + "unplugged": true + }, + "@iceshrimp/koa-openapi@2.4.0": { + "unplugged": true } } } diff --git a/packages/backend/package.json b/packages/backend/package.json index 76ad27ae5..deeebeca2 100644 --- a/packages/backend/package.json +++ b/packages/backend/package.json @@ -28,7 +28,7 @@ "@bull-board/ui": "5.6.0", "@discordapp/twemoji": "14.1.2", "@hapi/boom": "^10.0.1", - "@iceshrimp/koa-openapi": "^2.2.0", + "@iceshrimp/koa-openapi": "^2.4.1", "@koa/cors": "3.4.3", "@koa/multer": "3.0.2", "@koa/router": "9.0.1", diff --git a/packages/backend/src/server/api/web/controllers/auth.ts b/packages/backend/src/server/api/web/controllers/auth.ts index c5e5b0e32..570946b2e 100644 --- a/packages/backend/src/server/api/web/controllers/auth.ts +++ b/packages/backend/src/server/api/web/controllers/auth.ts @@ -1,4 +1,4 @@ -import { Controller, Get, Post, Body, CurrentUser, Flow } from "@iceshrimp/koa-openapi"; +import { Controller, Get, Post, Body, CurrentUser, Flow, Description } from "@iceshrimp/koa-openapi"; import type { ILocalUser } from "@/models/entities/user.js"; import type { AuthRequest, AuthResponse } from "@/server/api/web/entities/auth.js"; import type { Session } from "@/models/entities/session.js"; @@ -9,6 +9,7 @@ import { AuthHandler } from "@/server/api/web/handlers/auth.js"; @Controller('/auth') export class AuthController { @Get('/') + @Description("Get the authentication status") async getAuthStatus( @CurrentUser() me: ILocalUser | null, @CurrentSession() session: Session | null, @@ -18,6 +19,7 @@ export class AuthController { @Post('/') @Flow([RatelimitRouteMiddleware("auth", 10, 60000, true)]) + @Description("Log in as a user and receive a auth token on success") async login(@Body({ required: true }) request: AuthRequest): Promise { return AuthHandler.login(request); } diff --git a/packages/backend/src/server/api/web/controllers/note.ts b/packages/backend/src/server/api/web/controllers/note.ts index ea1f425a2..a393b1fdd 100644 --- a/packages/backend/src/server/api/web/controllers/note.ts +++ b/packages/backend/src/server/api/web/controllers/note.ts @@ -1,4 +1,4 @@ -import { Controller, Get, CurrentUser, Params, } from "@iceshrimp/koa-openapi"; +import { Controller, Get, CurrentUser, Params, Description, } from "@iceshrimp/koa-openapi"; import type { ILocalUser } from "@/models/entities/user.js"; import { NoteHandler } from "@/server/api/web/handlers/note.js"; import { NoteResponse } from "@/server/api/web/entities/note.js"; @@ -7,6 +7,7 @@ import { notFound } from "@hapi/boom"; @Controller('/note') export class NoteController { @Get('/:id') + @Description("Get the specified note") async getNote( @CurrentUser() me: ILocalUser | null, @Params('id') id: string, diff --git a/packages/backend/src/server/api/web/controllers/timeline.ts b/packages/backend/src/server/api/web/controllers/timeline.ts index 3f83f739d..74a615554 100644 --- a/packages/backend/src/server/api/web/controllers/timeline.ts +++ b/packages/backend/src/server/api/web/controllers/timeline.ts @@ -1,4 +1,4 @@ -import { Controller, CurrentUser, Flow, Get, Params, Query } from "@iceshrimp/koa-openapi"; +import { Controller, CurrentUser, Description, Flow, Get, Params, Query } from "@iceshrimp/koa-openapi"; import { UserResponse } from "@/server/api/web/entities/user.js"; import { TimelineResponse } from "@/server/api/web/entities/note.js"; import type { ILocalUser } from "@/models/entities/user.js"; @@ -10,6 +10,7 @@ import { AuthorizationMiddleware } from "@/server/api/web/middleware/auth.js"; export class TimelineController { @Get('/home') @Flow([AuthorizationMiddleware()]) + @Description("Get the home timeline") async getHomeTimeline( @CurrentUser() me: ILocalUser, @Query('replies') replies: boolean = true, diff --git a/packages/backend/src/server/api/web/controllers/user.ts b/packages/backend/src/server/api/web/controllers/user.ts index 0e167e5da..3d62cd44c 100644 --- a/packages/backend/src/server/api/web/controllers/user.ts +++ b/packages/backend/src/server/api/web/controllers/user.ts @@ -1,4 +1,4 @@ -import { Controller, CurrentUser, Get, Params, Query } from "@iceshrimp/koa-openapi"; +import { Controller, CurrentUser, Description, Get, Params, Query } from "@iceshrimp/koa-openapi"; import { UserResponse } from "@/server/api/web/entities/user.js"; import { TimelineResponse } from "@/server/api/web/entities/note.js"; import type { ILocalUser } from "@/models/entities/user.js"; @@ -7,6 +7,7 @@ import { UserHandler } from "@/server/api/web/handlers/user.js"; @Controller('/user') export class UserController { @Get('/:id') + @Description("Get information on the specified user") async getUser( @CurrentUser() me: ILocalUser | null, @Params('id') id: string, @@ -16,6 +17,7 @@ export class UserController { } @Get('/:id/notes') + @Description("Get the specified user's notes") async getUserNotes( @CurrentUser() me: ILocalUser | null, @Params('id') id: string, diff --git a/yarn.lock b/yarn.lock index e878a3b8d..9c2649076 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1204,9 +1204,9 @@ __metadata: languageName: node linkType: hard -"@iceshrimp/koa-openapi@npm:^2.2.0": - version: 2.2.0 - resolution: "@iceshrimp/koa-openapi@npm:2.2.0::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.2.0%2Fkoa-openapi-2.2.0.tgz" +"@iceshrimp/koa-openapi@npm:^2.4.1": + version: 2.4.1 + resolution: "@iceshrimp/koa-openapi@npm:2.4.1::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.4.1%2Fkoa-openapi-2.4.1.tgz" dependencies: "@hapi/boom": "npm:^10.0.1" "@koa/cors": "npm:^4.0.0" @@ -1221,7 +1221,7 @@ __metadata: lodash: "npm:^4.17.21" openapi-types: "npm:^12.1.3" reflect-metadata: "npm:*" - checksum: a7ff2c0b1a6fa54dacb9cc9a84d6a3008928f76396e47be42ddf93456f98c55bca42b027db378035b7f9d336ee703e44deb2a0e7d55167ddb081ff066c27f0a0 + checksum: 5270b64aa4131de59f624b4c9afb669118fb611a57118cb984a9b2ded83a8d6097b2c84eb516c68ec7b0b27ebdead637ee8cfeccb07a46da0bc5dda59b2015a5 languageName: node linkType: hard @@ -5414,7 +5414,7 @@ __metadata: "@bull-board/ui": "npm:5.6.0" "@discordapp/twemoji": "npm:14.1.2" "@hapi/boom": "npm:^10.0.1" - "@iceshrimp/koa-openapi": "npm:^2.2.0" + "@iceshrimp/koa-openapi": "npm:^2.4.1" "@koa/cors": "npm:3.4.3" "@koa/multer": "npm:3.0.2" "@koa/router": "npm:9.0.1" @@ -11560,6 +11560,10 @@ __metadata: dependenciesMeta: "@discordapp/twemoji@14.1.2": unplugged: true + "@iceshrimp/koa-openapi@2.3.0": + unplugged: true + "@iceshrimp/koa-openapi@2.4.0": + unplugged: true languageName: unknown linkType: soft