161sh/iceshrimp-161sh
1
0
Fork 0
mirror of https://iceshrimp.dev/crimekillz/iceshrimp-161sh.git synced 2024-11-22 20:23:49 +01:00
Code Issues Packages Projects Releases Wiki Activity

[backend/web-api] Add response descriptions and status codes

Browse Source
This commit is contained in:
Laura Hausmann 2023-12-12 19:23:39 +01:00
parent ddfe8bb48e
commit f4dcd08e89
No known key found for this signature in database
GPG Key ID: D044E84C5BE01605
10 changed files with 40 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.pnp.cjs generated
View File

@ -1898,10 +1898,10 @@ const RAW_RUNTIME_STATE =
}]\ }]\
]],\ ]],\
["@iceshrimp/koa-openapi", [\ ["@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", {\ ["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.4.1-8c7362549b-5270b64aa4.zip/node_modules/@iceshrimp/koa-openapi/",\ "packageLocation": "./.yarn/cache/@iceshrimp-koa-openapi-npm-2.7.0-37778d7452-21685db4ea.zip/node_modules/@iceshrimp/koa-openapi/",\
"packageDependencies": [\ "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"],\ ["@hapi/boom", "npm:10.0.1"],\
["@koa/cors", "npm:4.0.0"],\ ["@koa/cors", "npm:4.0.0"],\
["@koa/router", "npm:12.0.1"],\ ["@koa/router", "npm:12.0.1"],\
@ -1911,7 +1911,7 @@ const RAW_RUNTIME_STATE =
["koa", "npm:2.14.2"],\ ["koa", "npm:2.14.2"],\
["koa-body", "npm:6.0.1"],\ ["koa-body", "npm:6.0.1"],\
["koa-helmet", "npm:7.0.2"],\ ["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"],\ ["lodash", "npm:4.17.21"],\
["openapi-types", "npm:12.1.3"],\ ["openapi-types", "npm:12.1.3"],\
["reflect-metadata", "npm:0.1.13"]\ ["reflect-metadata", "npm:0.1.13"]\
@ -7217,7 +7217,7 @@ const RAW_RUNTIME_STATE =
["@bull-board/ui", "npm:5.6.0"],\ ["@bull-board/ui", "npm:5.6.0"],\
["@discordapp/twemoji", "npm:14.1.2"],\ ["@discordapp/twemoji", "npm:14.1.2"],\
["@hapi/boom", "npm:10.0.1"],\ ["@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/cors", "npm:3.4.3"],\
["@koa/multer", "virtual:aa59773ac87791c4813d53447077fcf8a847d6de5a301d34dc31286584b1dbb26d30d3adb5b4c41c1e8aea04371e926fda05c09c6253647c432e11d872a304ba#npm:3.0.2"],\ ["@koa/multer", "virtual:aa59773ac87791c4813d53447077fcf8a847d6de5a301d34dc31286584b1dbb26d30d3adb5b4c41c1e8aea04371e926fda05c09c6253647c432e11d872a304ba#npm:3.0.2"],\
["@koa/router", "npm:9.0.1"],\ ["@koa/router", "npm:9.0.1"],\
@ -17145,10 +17145,10 @@ const RAW_RUNTIME_STATE =
],\ ],\
"linkType": "SOFT"\ "linkType": "SOFT"\
}],\ }],\
["virtual:8c7362549be2320b14415acd0a28c20c4a28a61f50998f521c19c171b924639d2efda4597f82a25044828aebf1f59af528473f27cfbb1764bf584786860b172c#npm:5.10.0", {\ ["virtual:37778d7452aa22a4b9b696d3401d761eb63cf07fe0900455c93a17ab008fd0bea8cb487e82bff1386539d52523936a6d87cd46d4e8395c6f97dee7afea734531#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/",\ "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": [\ "packageDependencies": [\
["koa2-swagger-ui", "virtual:8c7362549be2320b14415acd0a28c20c4a28a61f50998f521c19c171b924639d2efda4597f82a25044828aebf1f59af528473f27cfbb1764bf584786860b172c#npm:5.10.0"],\ ["koa2-swagger-ui", "virtual:37778d7452aa22a4b9b696d3401d761eb63cf07fe0900455c93a17ab008fd0bea8cb487e82bff1386539d52523936a6d87cd46d4e8395c6f97dee7afea734531#npm:5.10.0"],\
["@types/koa", null],\ ["@types/koa", null],\
["handlebars", "npm:4.7.8"],\ ["handlebars", "npm:4.7.8"],\
["lodash", "npm:4.17.21"],\ ["lodash", "npm:4.17.21"],\

BIN
.yarn/cache/@iceshrimp-koa-openapi-npm-2.4.1-8c7362549b-5270b64aa4.zip (Stored with Git LFS) vendored
View File

Binary file not shown.

BIN
.yarn/cache/@iceshrimp-koa-openapi-npm-2.7.0-37778d7452-21685db4ea.zip (Stored with Git LFS) vendored Normal file
View File

Binary file not shown.

3
package.json
View File

@ -82,6 +82,9 @@
}, },
"@iceshrimp/koa-openapi@2.4.0": { "@iceshrimp/koa-openapi@2.4.0": {
"unplugged": true "unplugged": true
},
"@iceshrimp/koa-openapi@2.5.0": {
"unplugged": true
} }
} }
} }

2
packages/backend/package.json
View File

@ -28,7 +28,7 @@
"@bull-board/ui": "5.6.0", "@bull-board/ui": "5.6.0",
"@discordapp/twemoji": "14.1.2", "@discordapp/twemoji": "14.1.2",
"@hapi/boom": "^10.0.1", "@hapi/boom": "^10.0.1",
"@iceshrimp/koa-openapi": "^2.4.1", "@iceshrimp/koa-openapi": "^2.7.0",
"@koa/cors": "3.4.3", "@koa/cors": "3.4.3",
"@koa/multer": "3.0.2", "@koa/multer": "3.0.2",
"@koa/router": "9.0.1", "@koa/router": "9.0.1",

6
packages/backend/src/server/api/web/controllers/auth.ts
View File

@ -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 { ILocalUser } from "@/models/entities/user.js";
import type { AuthRequest, AuthResponse } from "@/server/api/web/entities/auth.js"; import type { AuthRequest, AuthResponse } from "@/server/api/web/entities/auth.js";
import type { Session } from "@/models/entities/session.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 { export class AuthController {
@Get('/') @Get('/')
@Description("Get the authentication status") @Description("Get the authentication status")
@Returns(200, "Successful response")
async getAuthStatus( async getAuthStatus(
@CurrentUser() me: ILocalUser | null, @CurrentUser() me: ILocalUser | null,
@CurrentSession() session: Session | null, @CurrentSession() session: Session | null,
@ -20,6 +21,9 @@ export class AuthController {
@Post('/') @Post('/')
@Flow([RatelimitRouteMiddleware("auth", 10, 60000, true)]) @Flow([RatelimitRouteMiddleware("auth", 10, 60000, true)])
@Description("Log in as a user and receive a auth token on success") @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<AuthResponse> { async login(@Body({ required: true }) request: AuthRequest): Promise<AuthResponse> {
return AuthHandler.login(request); return AuthHandler.login(request);
} }

6
packages/backend/src/server/api/web/controllers/note.ts
View File

@ -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 type { ILocalUser } from "@/models/entities/user.js";
import { NoteHandler } from "@/server/api/web/handlers/note.js"; import { NoteHandler } from "@/server/api/web/handlers/note.js";
import { NoteResponse } from "@/server/api/web/entities/note.js"; import { NoteResponse } from "@/server/api/web/entities/note.js";
@ -7,7 +7,9 @@ import { notFound } from "@hapi/boom";
@Controller('/note') @Controller('/note')
export class NoteController { export class NoteController {
@Get('/:id') @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( async getNote(
@CurrentUser() me: ILocalUser | null, @CurrentUser() me: ILocalUser | null,
@Params('id') id: string, @Params('id') id: string,

4
packages/backend/src/server/api/web/controllers/timeline.ts
View File

@ -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 { UserResponse } from "@/server/api/web/entities/user.js";
import { TimelineResponse } from "@/server/api/web/entities/note.js"; import { TimelineResponse } from "@/server/api/web/entities/note.js";
import type { ILocalUser } from "@/models/entities/user.js"; import type { ILocalUser } from "@/models/entities/user.js";
@ -11,6 +11,8 @@ export class TimelineController {
@Get('/home') @Get('/home')
@Flow([AuthorizationMiddleware()]) @Flow([AuthorizationMiddleware()])
@Description("Get the home timeline") @Description("Get the home timeline")
@Returns(200, "Successful response")
@Returns(401, "Authorization header is missing or invalid")
async getHomeTimeline( async getHomeTimeline(
@CurrentUser() me: ILocalUser, @CurrentUser() me: ILocalUser,
@Query('replies') replies: boolean = true, @Query('replies') replies: boolean = true,

8
packages/backend/src/server/api/web/controllers/user.ts
View File

@ -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 { UserResponse } from "@/server/api/web/entities/user.js";
import { TimelineResponse } from "@/server/api/web/entities/note.js"; import { TimelineResponse } from "@/server/api/web/entities/note.js";
import type { ILocalUser } from "@/models/entities/user.js"; import type { ILocalUser } from "@/models/entities/user.js";
@ -7,7 +7,9 @@ import { UserHandler } from "@/server/api/web/handlers/user.js";
@Controller('/user') @Controller('/user')
export class UserController { export class UserController {
@Get('/:id') @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( async getUser(
@CurrentUser() me: ILocalUser | null, @CurrentUser() me: ILocalUser | null,
@Params('id') id: string, @Params('id') id: string,
@ -18,6 +20,8 @@ export class UserController {
@Get('/:id/notes') @Get('/:id/notes')
@Description("Get the specified user's notes") @Description("Get the specified user's notes")
@Returns(200, "Successful response")
@Returns(404, "The specified user does not exist")
async getUserNotes( async getUserNotes(
@CurrentUser() me: ILocalUser | null, @CurrentUser() me: ILocalUser | null,
@Params('id') id: string, @Params('id') id: string,

12
yarn.lock
View File

@ -1204,9 +1204,9 @@ __metadata:
languageName: node languageName: node
linkType: hard linkType: hard
"@iceshrimp/koa-openapi@npm:^2.4.1": "@iceshrimp/koa-openapi@npm:^2.7.0":
version: 2.4.1 version: 2.7.0
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" 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: dependencies:
"@hapi/boom": "npm:^10.0.1" "@hapi/boom": "npm:^10.0.1"
"@koa/cors": "npm:^4.0.0" "@koa/cors": "npm:^4.0.0"
@ -1221,7 +1221,7 @@ __metadata:
lodash: "npm:^4.17.21" lodash: "npm:^4.17.21"
openapi-types: "npm:^12.1.3" openapi-types: "npm:^12.1.3"
reflect-metadata: "npm:*" reflect-metadata: "npm:*"
checksum: 5270b64aa4131de59f624b4c9afb669118fb611a57118cb984a9b2ded83a8d6097b2c84eb516c68ec7b0b27ebdead637ee8cfeccb07a46da0bc5dda59b2015a5 checksum: 21685db4ea05494b885461bddd40312707106cdbf11e68d167136e827fd8b27fc709c0933b81e51432711d7eafc1f47fc03c909d977e38f3a98a8f700d9715ed
languageName: node languageName: node
linkType: hard linkType: hard
@ -5414,7 +5414,7 @@ __metadata:
"@bull-board/ui": "npm:5.6.0" "@bull-board/ui": "npm:5.6.0"
"@discordapp/twemoji": "npm:14.1.2" "@discordapp/twemoji": "npm:14.1.2"
"@hapi/boom": "npm:^10.0.1" "@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/cors": "npm:3.4.3"
"@koa/multer": "npm:3.0.2" "@koa/multer": "npm:3.0.2"
"@koa/router": "npm:9.0.1" "@koa/router": "npm:9.0.1"
@ -11564,6 +11564,8 @@ __metadata:
unplugged: true unplugged: true
"@iceshrimp/koa-openapi@2.4.0": "@iceshrimp/koa-openapi@2.4.0":
unplugged: true unplugged: true
"@iceshrimp/koa-openapi@2.5.0":
unplugged: true
languageName: unknown languageName: unknown
linkType: soft linkType: soft