Add OpenAPI schema generation and validation for API routes

This commit is contained in:
Mike Cao committed 2026-08-31 19:37:37 -07:00
1 parent 5d822e6c7e
commit 5ce5664b29
25 files changed
+2019 -52

No files matched your search

+71
View File
@@ -0,0 +1,71 @@
import { z } from 'zod';
import { defineOperation } from '@/openapi/operation';
import {
badRequestResponse,
jsonResponse,
serviceUnavailableResponse,
unauthorizedResponse,
} from '@/openapi/schemas';
import { loginRequestSchema } from './schema';
const loginTeamSchema = z
.object({
id: z.uuid(),
name: z.string(),
logoUrl: z.string().nullable(),
})
.meta({ id: 'LoginTeam' });
const loginUserSchema = z
.object({
id: z.uuid(),
username: z.string(),
role: z.string(),
createdAt: z.iso.datetime().nullable(),
isAdmin: z.boolean(),
teams: z.array(loginTeamSchema),
})
.meta({ id: 'LoginUser' });
export const loginResponseSchema = z
.union([
z.object({
requiresTwoFactor: z.literal(true),
partialToken: z.string(),
}),
z.object({
token: z.string(),
user: loginUserSchema,
}),
])
.meta({ id: 'LoginResponse' });
const loginOperation = defineOperation({
method: 'post',
path: '/api/auth/login',
audience: 'public',
auth: 'none',
operation: {
operationId: 'login',
summary: 'Log in',
description:
'Authenticates a self-hosted Umami user. Users with two-factor authentication receive a short-lived partial token instead of a full bearer token.',
tags: ['Authentication'],
requestBody: {
required: true,
content: {
'application/json': {
schema: loginRequestSchema,
},
},
},
responses: {
'200': jsonResponse(loginResponseSchema, 'Authenticated successfully.'),
'400': badRequestResponse,
'401': unauthorizedResponse,
'503': serviceUnavailableResponse,
},
},
});
export const operations = [loginOperation] as const;
+2 -7
View File
@@ -1,4 +1,3 @@
import { z } from 'zod';
import { saveAuth } from '@/lib/auth';
import { ROLES } from '@/lib/constants';
import { hash, secret } from '@/lib/crypto';
@@ -10,14 +9,10 @@ import { parseRequest } from '@/lib/request';
import { json, serviceUnavailable, unauthorized } from '@/lib/response';
import { getTwoFactorConfigurationError, isTwoFactorConfigured } from '@/lib/two-factor/crypto';
import { getAllUserTeams, getUserByUsername } from '@/queries/prisma';
import { loginRequestSchema } from './schema';
export async function POST(request: Request) {
const schema = z.object({
username: z.string(),
password: z.string(),
});
const { body, error } = await parseRequest(request, schema, { skipAuth: true });
const { body, error } = await parseRequest(request, loginRequestSchema, { skipAuth: true });
if (error) {
return error();
+8
View File
@@ -0,0 +1,8 @@
import { z } from 'zod';
export const loginRequestSchema = z
.object({
username: z.string().meta({ description: 'Umami username.' }),
password: z.string().meta({ description: 'Umami password.' }),
})
.meta({ id: 'LoginRequest' });
@@ -0,0 +1,86 @@
import { defineOperation } from '@/openapi/operation';
import {
badRequestResponse,
jsonResponse,
okSchema,
serverErrorResponse,
unauthorizedResponse,
} from '@/openapi/schemas';
import { updateWebsiteRequestSchema } from '../request-schema';
import { websiteIdPathSchema, websiteSchema } from '../response-schema';
const getWebsiteOperation = defineOperation({
method: 'get',
path: '/api/websites/{websiteId}',
audience: 'public',
auth: 'bearer-or-share',
operation: {
operationId: 'getWebsite',
summary: 'Get a website',
tags: ['Websites'],
requestParams: {
path: websiteIdPathSchema,
},
responses: {
'200': jsonResponse(
websiteSchema.nullable(),
'Website details, or null if it does not exist.',
),
'401': unauthorizedResponse,
},
},
});
const updateWebsiteOperation = defineOperation({
method: 'post',
path: '/api/websites/{websiteId}',
audience: 'public',
auth: 'bearer',
operation: {
operationId: 'updateWebsite',
summary: 'Update a website',
tags: ['Websites'],
requestParams: {
path: websiteIdPathSchema,
},
requestBody: {
required: true,
content: {
'application/json': {
schema: updateWebsiteRequestSchema,
},
},
},
responses: {
'200': jsonResponse(websiteSchema, 'Website updated.'),
'400': badRequestResponse,
'401': unauthorizedResponse,
'500': serverErrorResponse,
},
},
});
const deleteWebsiteOperation = defineOperation({
method: 'delete',
path: '/api/websites/{websiteId}',
audience: 'public',
auth: 'bearer',
operation: {
operationId: 'deleteWebsite',
summary: 'Delete a website',
tags: ['Websites'],
requestParams: {
path: websiteIdPathSchema,
},
responses: {
'200': jsonResponse(okSchema, 'Website deleted.'),
'401': unauthorizedResponse,
},
},
});
export const operations = [
getWebsiteOperation,
updateWebsiteOperation,
deleteWebsiteOperation,
] as const;
+3 -21
View File
@@ -1,6 +1,5 @@
import { z } from 'zod';
import type { Prisma } from '@/generated/prisma/client';
import { DOMAIN_REGEX, ENTITY_TYPE } from '@/lib/constants';
import { ENTITY_TYPE } from '@/lib/constants';
import { uuid } from '@/lib/crypto';
import { getRecorderConfig, getRecorderEnabled } from '@/lib/recorder';
import { parseRequest } from '@/lib/request';
@@ -14,6 +13,7 @@ import {
getWebsite,
updateWebsite,
} from '@/queries/prisma';
import { updateWebsiteRequestSchema } from '../request-schema';
export async function GET(
request: Request,
@@ -40,25 +40,7 @@ export async function POST(
request: Request,
{ params }: { params: Promise<{ websiteId: string }> },
) {
const schema = z.object({
name: z.string().trim().min(1).max(100).optional(),
domain: z.string().trim().regex(DOMAIN_REGEX).max(500).optional(),
shareId: z.string().max(50).nullable().optional(),
replayConfig: z
.object({
replayEnabled: z.boolean().optional(),
heatmapEnabled: z.boolean().optional(),
sampleRate: z.number().min(0).max(1).optional(),
heatmapSampleRate: z.number().min(0).max(1).optional(),
maskLevel: z.enum(['strict', 'moderate']).optional(),
maxDuration: z.number().int().positive().optional(),
blockSelector: z.string().optional(),
})
.nullable()
.optional(),
});
const { auth, body, error } = await parseRequest(request, schema);
const { auth, body, error } = await parseRequest(request, updateWebsiteRequestSchema);
if (error) {
return error();
+52
View File
@@ -0,0 +1,52 @@
import { defineOperation } from '@/openapi/operation';
import { badRequestResponse, jsonResponse, unauthorizedResponse } from '@/openapi/schemas';
import { createWebsiteRequestSchema, listWebsitesQuerySchema } from './request-schema';
import { websitePageSchema, websiteSchema } from './response-schema';
const listWebsitesOperation = defineOperation({
method: 'get',
path: '/api/websites',
audience: 'public',
auth: 'bearer',
operation: {
operationId: 'listWebsites',
summary: 'List websites',
description: 'Returns websites owned by the authenticated user.',
tags: ['Websites'],
requestParams: {
query: listWebsitesQuerySchema,
},
responses: {
'200': jsonResponse(websitePageSchema, 'A page of websites.'),
'400': badRequestResponse,
'401': unauthorizedResponse,
},
},
});
const createWebsiteOperation = defineOperation({
method: 'post',
path: '/api/websites',
audience: 'public',
auth: 'bearer',
operation: {
operationId: 'createWebsite',
summary: 'Create a website',
tags: ['Websites'],
requestBody: {
required: true,
content: {
'application/json': {
schema: createWebsiteRequestSchema,
},
},
},
responses: {
'200': jsonResponse(websiteSchema, 'Website created.'),
'400': badRequestResponse,
'401': unauthorizedResponse,
},
},
});
export const operations = [listWebsitesOperation, createWebsiteOperation] as const;
+45
View File
@@ -0,0 +1,45 @@
import { z } from 'zod';
import { DOMAIN_REGEX } from '@/lib/constants';
import { pagingParams, searchParams, sortingParams } from '@/lib/schema';
export const replayConfigInputSchema = z
.object({
replayEnabled: z.boolean().optional(),
heatmapEnabled: z.boolean().optional(),
sampleRate: z.number().min(0).max(1).optional(),
heatmapSampleRate: z.number().min(0).max(1).optional(),
maskLevel: z.enum(['strict', 'moderate']).optional(),
maxDuration: z.number().int().positive().optional(),
blockSelector: z.string().optional(),
})
.meta({ id: 'ReplayConfigInput' });
export const listWebsitesQuerySchema = z
.object({
...pagingParams,
...searchParams,
...sortingParams,
includeTeams: z.string().optional().meta({
description: 'When present, include websites accessible through owned or managed teams.',
}),
})
.meta({ id: 'ListWebsitesQuery' });
export const createWebsiteRequestSchema = z
.object({
name: z.string().trim().min(1).max(100),
domain: z.string().trim().regex(DOMAIN_REGEX).max(500),
shareId: z.string().max(50).nullable().optional(),
teamId: z.uuid().nullable().optional(),
id: z.uuid().nullable().optional(),
})
.meta({ id: 'CreateWebsiteRequest' });
export const updateWebsiteRequestSchema = z
.object({
name: z.string().trim().min(1).max(100).optional(),
domain: z.string().trim().regex(DOMAIN_REGEX).max(500).optional(),
shareId: z.string().max(50).nullable().optional(),
replayConfig: replayConfigInputSchema.nullable().optional(),
})
.meta({ id: 'UpdateWebsiteRequest' });
+60
View File
@@ -0,0 +1,60 @@
import { z } from 'zod';
const nullableUuidSchema = z.uuid().nullable();
const nullableDateTimeSchema = z.iso.datetime().nullable();
export const replayConfigSchema = z
.looseObject({
replayEnabled: z.boolean().optional(),
heatmapEnabled: z.boolean().optional(),
sampleRate: z.number().min(0).max(1).optional(),
heatmapSampleRate: z.number().min(0).max(1).optional(),
maskLevel: z.enum(['strict', 'moderate']).optional(),
maxDuration: z.number().int().positive().optional(),
blockSelector: z.string().optional(),
})
.meta({ id: 'ReplayConfig' });
const websiteUserSchema = z
.object({
id: z.uuid(),
username: z.string(),
})
.meta({ id: 'WebsiteUser' });
export const websiteSchema = z
.object({
id: z.uuid(),
name: z.string(),
domain: z.string().nullable(),
resetAt: nullableDateTimeSchema,
userId: nullableUuidSchema,
teamId: nullableUuidSchema,
createdBy: nullableUuidSchema,
createdAt: nullableDateTimeSchema,
updatedAt: nullableDateTimeSchema,
deletedAt: nullableDateTimeSchema,
recorderEnabled: z.boolean(),
replayConfig: replayConfigSchema.nullable(),
shareId: z.string().nullable(),
user: websiteUserSchema.optional(),
})
.meta({ id: 'Website' });
export const websitePageSchema = z
.object({
data: z.array(websiteSchema),
count: z.number().int().nonnegative(),
page: z.number().int().positive(),
pageSize: z.number().int().nonnegative(),
orderBy: z.string().optional(),
search: z.string().optional(),
})
.meta({ id: 'WebsitePage' });
export const websiteIdPathSchema = z.object({
websiteId: z.uuid().meta({
description: 'Website ID.',
param: { description: 'Website ID.' },
}),
});
+4 -20
View File
@@ -1,24 +1,16 @@
import { z } from 'zod';
import { DOMAIN_REGEX, ENTITY_TYPE } from '@/lib/constants';
import { ENTITY_TYPE } from '@/lib/constants';
import { uuid } from '@/lib/crypto';
import { fetchAccount, fetchTeam } from '@/lib/load';
import { getQueryFilters, parseRequest } from '@/lib/request';
import { json, unauthorized } from '@/lib/response';
import { pagingParams, searchParams, sortingParams } from '@/lib/schema';
import { getCloudWebsiteLimit } from '@/lib/subscription';
import { canCreateTeamWebsite, canCreateWebsite } from '@/permissions';
import { createShare, createWebsite, getTeamWebsiteCount, getWebsiteCount } from '@/queries/prisma';
import { getAllUserWebsitesIncludingTeamAccess, getUserWebsites } from '@/queries/prisma/website';
import { createWebsiteRequestSchema, listWebsitesQuerySchema } from './request-schema';
export async function GET(request: Request) {
const schema = z.object({
...pagingParams,
...searchParams,
...sortingParams,
includeTeams: z.string().optional(),
});
const { auth, query, error } = await parseRequest(request, schema);
const { auth, query, error } = await parseRequest(request, listWebsitesQuerySchema);
if (error) {
return error();
@@ -36,15 +28,7 @@ export async function GET(request: Request) {
}
export async function POST(request: Request) {
const schema = z.object({
name: z.string().trim().min(1).max(100),
domain: z.string().trim().regex(DOMAIN_REGEX).max(500),
shareId: z.string().max(50).nullable().optional(),
teamId: z.uuid().nullable().optional(),
id: z.uuid().nullable().optional(),
});
const { auth, body, error } = await parseRequest(request, schema);
const { auth, body, error } = await parseRequest(request, createWebsiteRequestSchema);
if (error) {
return error();