From f4dcd08e8944e9441081f509ead00e9770ec731a Mon Sep 17 00:00:00 2001 From: Laura Hausmann Date: Tue, 12 Dec 2023 19:23:39 +0100 Subject: [PATCH] [backend/web-api] Add response descriptions and status codes --- .pnp.cjs | 16 ++++++++-------- ...a-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip | 3 --- ...a-openapi-npm-2.7.0-37778d7452-21685db4ea.zip | 3 +++ package.json | 3 +++ packages/backend/package.json | 2 +- .../src/server/api/web/controllers/auth.ts | 6 +++++- .../src/server/api/web/controllers/note.ts | 6 ++++-- .../src/server/api/web/controllers/timeline.ts | 4 +++- .../src/server/api/web/controllers/user.ts | 8 ++++++-- yarn.lock | 12 +++++++----- 10 files changed, 40 insertions(+), 23 deletions(-) delete mode 100644 .yarn/cache/@iceshrimp-koa-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip create mode 100644 .yarn/cache/@iceshrimp-koa-openapi-npm-2.7.0-37778d7452-21685db4ea.zip diff --git a/.pnp.cjs b/.pnp.cjs index b6245c655..a950f8b20 100755 --- a/.pnp.cjs +++ b/.pnp.cjs @@ -1898,10 +1898,10 @@ const RAW_RUNTIME_STATE = }]\ ]],\ ["@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/",\ + ["npm:2.7.0::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.7.0%2Fkoa-openapi-2.7.0.tgz", {\ + "packageLocation": "./.yarn/cache/@iceshrimp-koa-openapi-npm-2.7.0-37778d7452-21685db4ea.zip/node_modules/@iceshrimp/koa-openapi/",\ "packageDependencies": [\ - ["@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"],\ + ["@iceshrimp/koa-openapi", "npm:2.7.0::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.7.0%2Fkoa-openapi-2.7.0.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:8c7362549be2320b14415acd0a28c20c4a28a61f50998f521c19c171b924639d2efda4597f82a25044828aebf1f59af528473f27cfbb1764bf584786860b172c#npm:5.10.0"],\ + ["koa2-swagger-ui", "virtual:37778d7452aa22a4b9b696d3401d761eb63cf07fe0900455c93a17ab008fd0bea8cb487e82bff1386539d52523936a6d87cd46d4e8395c6f97dee7afea734531#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.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"],\ + ["@iceshrimp/koa-openapi", "npm:2.7.0::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.7.0%2Fkoa-openapi-2.7.0.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: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/",\ + ["virtual:37778d7452aa22a4b9b696d3401d761eb63cf07fe0900455c93a17ab008fd0bea8cb487e82bff1386539d52523936a6d87cd46d4e8395c6f97dee7afea734531#npm:5.10.0", {\ + "packageLocation": "./.yarn/__virtual__/koa2-swagger-ui-virtual-c4b42f8a3a/0/cache/koa2-swagger-ui-npm-5.10.0-54bce94261-40575d377d.zip/node_modules/koa2-swagger-ui/",\ "packageDependencies": [\ - ["koa2-swagger-ui", "virtual:8c7362549be2320b14415acd0a28c20c4a28a61f50998f521c19c171b924639d2efda4597f82a25044828aebf1f59af528473f27cfbb1764bf584786860b172c#npm:5.10.0"],\ + ["koa2-swagger-ui", "virtual:37778d7452aa22a4b9b696d3401d761eb63cf07fe0900455c93a17ab008fd0bea8cb487e82bff1386539d52523936a6d87cd46d4e8395c6f97dee7afea734531#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.4.1-8c7362549b-5270b64aa4.zip b/.yarn/cache/@iceshrimp-koa-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip deleted file mode 100644 index a483d88fd..000000000 --- a/.yarn/cache/@iceshrimp-koa-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:baf88bc93a6338fe4193fcaff6a1353ff3801370029d44ad916eaf9f09301670 -size 101881 diff --git a/.yarn/cache/@iceshrimp-koa-openapi-npm-2.7.0-37778d7452-21685db4ea.zip b/.yarn/cache/@iceshrimp-koa-openapi-npm-2.7.0-37778d7452-21685db4ea.zip new file mode 100644 index 000000000..306386968 --- /dev/null +++ b/.yarn/cache/@iceshrimp-koa-openapi-npm-2.7.0-37778d7452-21685db4ea.zip @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3406d33f6247cfd9a25ede089dcacde3982d5f8947c6265d1e4b16c4dc6257e8 +size 103526 diff --git a/package.json b/package.json index 9510cc0fd..7cc9f21d2 100644 --- a/package.json +++ b/package.json @@ -82,6 +82,9 @@ }, "@iceshrimp/koa-openapi@2.4.0": { "unplugged": true + }, + "@iceshrimp/koa-openapi@2.5.0": { + "unplugged": true } } } diff --git a/packages/backend/package.json b/packages/backend/package.json index deeebeca2..4f3b029dd 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.4.1", + "@iceshrimp/koa-openapi": "^2.7.0", "@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 570946b2e..cc51c7b5d 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, Description } from "@iceshrimp/koa-openapi"; +import { Controller, Get, Post, Body, CurrentUser, Flow, Description, Returns } 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"; @@ -10,6 +10,7 @@ import { AuthHandler } from "@/server/api/web/handlers/auth.js"; export class AuthController { @Get('/') @Description("Get the authentication status") + @Returns(200, "Successful response") async getAuthStatus( @CurrentUser() me: ILocalUser | null, @CurrentSession() session: Session | null, @@ -20,6 +21,9 @@ export class AuthController { @Post('/') @Flow([RatelimitRouteMiddleware("auth", 10, 60000, true)]) @Description("Log in as a user and receive a auth token on success") + @Returns(200, "Successful response") + @Returns(400, "Request body is missing or invalid") + @Returns(401, "Specified username or password are invalid") 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 a393b1fdd..73f5ad41f 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, Description, } from "@iceshrimp/koa-openapi"; +import { Controller, Get, CurrentUser, Params, Description, Returns } 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,7 +7,9 @@ import { notFound } from "@hapi/boom"; @Controller('/note') export class NoteController { @Get('/:id') - @Description("Get the specified note") + @Description("Returns the specified note") + @Returns(200, "Successful response") + @Returns(404, "The specified note either doesn't exist or is not visible for the authenticated user (if any)") 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 74a615554..1714e2f24 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, Description, Flow, Get, Params, Query } from "@iceshrimp/koa-openapi"; +import { Controller, CurrentUser, Description, Flow, Get, Params, Query, Returns } 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"; @@ -11,6 +11,8 @@ export class TimelineController { @Get('/home') @Flow([AuthorizationMiddleware()]) @Description("Get the home timeline") + @Returns(200, "Successful response") + @Returns(401, "Authorization header is missing or invalid") 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 3d62cd44c..985f6ad00 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, Description, Get, Params, Query } from "@iceshrimp/koa-openapi"; +import { Controller, CurrentUser, Description, Get, Params, Query, Returns } 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,7 +7,9 @@ import { UserHandler } from "@/server/api/web/handlers/user.js"; @Controller('/user') export class UserController { @Get('/:id') - @Description("Get information on the specified user") + @Description("Returns information on the specified user") + @Returns(200, "Successful response") + @Returns(404, "The specified user does not exist") async getUser( @CurrentUser() me: ILocalUser | null, @Params('id') id: string, @@ -18,6 +20,8 @@ export class UserController { @Get('/:id/notes') @Description("Get the specified user's notes") + @Returns(200, "Successful response") + @Returns(404, "The specified user does not exist") async getUserNotes( @CurrentUser() me: ILocalUser | null, @Params('id') id: string, diff --git a/yarn.lock b/yarn.lock index 9c2649076..85f224fd4 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1204,9 +1204,9 @@ __metadata: languageName: node linkType: hard -"@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" +"@iceshrimp/koa-openapi@npm:^2.7.0": + version: 2.7.0 + resolution: "@iceshrimp/koa-openapi@npm:2.7.0::__archiveUrl=https%3A%2F%2Ficeshrimp.dev%2Fapi%2Fpackages%2Ficeshrimp%2Fnpm%2F%2540iceshrimp%252Fkoa-openapi%2F-%2F2.7.0%2Fkoa-openapi-2.7.0.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: 5270b64aa4131de59f624b4c9afb669118fb611a57118cb984a9b2ded83a8d6097b2c84eb516c68ec7b0b27ebdead637ee8cfeccb07a46da0bc5dda59b2015a5 + checksum: 21685db4ea05494b885461bddd40312707106cdbf11e68d167136e827fd8b27fc709c0933b81e51432711d7eafc1f47fc03c909d977e38f3a98a8f700d9715ed 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.4.1" + "@iceshrimp/koa-openapi": "npm:^2.7.0" "@koa/cors": "npm:3.4.3" "@koa/multer": "npm:3.0.2" "@koa/router": "npm:9.0.1" @@ -11564,6 +11564,8 @@ __metadata: unplugged: true "@iceshrimp/koa-openapi@2.4.0": unplugged: true + "@iceshrimp/koa-openapi@2.5.0": + unplugged: true languageName: unknown linkType: soft