Skip to content

Commit d4f47ab

Browse files
brendan-kellambrendan-kellam
authored
docs: Improve API docs (#1066)
1 parent b674ad7 commit d4f47ab

File tree

8 files changed

+1427
-404
lines changed

8 files changed

+1427
-404
lines changed

‎docs/api-reference/sourcebot-public.openapi.json‎

Lines changed: 1046 additions & 225 deletions
Large diffs are not rendered by default.

‎docs/docs.json‎

Lines changed: 71 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"$schema": "https://mintlify.com/docs.json",
3-
"theme": "almond",
3+
"theme": "aspen",
44
"name": "Sourcebot",
55
"colors": {
66
"primary": "#851EE7",
@@ -12,10 +12,28 @@
1212
"eyebrows": "section"
1313
},
1414
"navigation": {
15-
"anchors": [
15+
"global": {
16+
"anchors": [
17+
{
18+
"anchor": "Changelog",
19+
"href": "https://sourcebot.dev/changelog",
20+
"icon": "list-check"
21+
},
22+
{
23+
"anchor": "Roadmap",
24+
"href": "https://github.com/sourcebot-dev/sourcebot/issues/459",
25+
"icon": "map"
26+
},
27+
{
28+
"anchor": "Support",
29+
"href": "https://github.com/sourcebot-dev/sourcebot/issues/new?template=get_help.md",
30+
"icon": "life-ring"
31+
}
32+
]
33+
},
34+
"tabs": [
1635
{
17-
"anchor": "Docs",
18-
"icon": "books",
36+
"tab": "Documentation",
1937
"groups": [
2038
{
2139
"group": "Getting Started",
@@ -73,17 +91,6 @@
7391
}
7492
]
7593
},
76-
{
77-
"group": "API Reference",
78-
"pages": [
79-
"docs/api-reference/overview",
80-
{
81-
"group": "Public API",
82-
"openapi": "api-reference/sourcebot-public.openapi.json",
83-
"directory": "docs/api-reference/public-api"
84-
}
85-
]
86-
},
8794
{
8895
"group": "Configuration",
8996
"pages": [
@@ -134,19 +141,55 @@
134141
]
135142
},
136143
{
137-
"anchor": "Changelog",
138-
"href": "https://sourcebot.dev/changelog",
139-
"icon": "list-check"
140-
},
141-
{
142-
"anchor": "Roadmap",
143-
"href": "https://github.com/sourcebot-dev/sourcebot/issues/459",
144-
"icon": "map"
145-
},
146-
{
147-
"anchor": "Support",
148-
"href": "https://github.com/sourcebot-dev/sourcebot/issues/new?template=get_help.md",
149-
"icon": "life-ring"
144+
"tab": "API Reference",
145+
"icon": "code",
146+
"openapi": "api-reference/sourcebot-public.openapi.json",
147+
"groups": [
148+
{
149+
"group": "Search & Navigation",
150+
"icon": "magnifying-glass",
151+
"pages": [
152+
"POST /api/search",
153+
"POST /api/find_definitions",
154+
"POST /api/find_references"
155+
]
156+
},
157+
{
158+
"group": "Repositories",
159+
"icon": "database",
160+
"pages": [
161+
"GET /api/repos"
162+
]
163+
},
164+
{
165+
"group": "Git",
166+
"icon": "code-branch",
167+
"pages": [
168+
"GET /api/diff",
169+
"GET /api/commits",
170+
"GET /api/source",
171+
"POST /api/tree"
172+
]
173+
},
174+
{
175+
"group": "Enterprise Management",
176+
"icon": "building-columns",
177+
"pages": [
178+
"GET /api/ee/user",
179+
"DELETE /api/ee/user",
180+
"GET /api/ee/users",
181+
"GET /api/ee/audit"
182+
]
183+
},
184+
{
185+
"group": "System",
186+
"icon": "server",
187+
"pages": [
188+
"GET /api/version",
189+
"GET /api/health"
190+
]
191+
}
192+
]
150193
}
151194
]
152195
},

‎docs/docs/api-reference/overview.mdx‎

Lines changed: 0 additions & 31 deletions
This file was deleted.

‎packages/web/src/app/api/(server)/commits/route.ts‎

Lines changed: 1 addition & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,10 @@
11
import { listCommits } from "@/features/git";
2+
import { listCommitsQueryParamsSchema } from "@/features/git/schemas";
23
import { apiHandler } from "@/lib/apiHandler";
34
import { buildLinkHeader } from "@/lib/pagination";
45
import { serviceErrorResponse, queryParamsSchemaValidationError } from "@/lib/serviceError";
56
import { isServiceError } from "@/lib/utils";
67
import { NextRequest } from "next/server";
7-
import { z } from "zod";
8-
9-
const listCommitsQueryParamsSchema = z.object({
10-
repo: z.string(),
11-
query: z.string().optional(),
12-
since: z.string().optional(),
13-
until: z.string().optional(),
14-
author: z.string().optional(),
15-
ref: z.string().optional(),
16-
path: z.string().optional(),
17-
page: z.coerce.number().int().positive().default(1),
18-
perPage: z.coerce.number().int().positive().max(100).default(50),
19-
});
208

219
export const GET = apiHandler(async (request: NextRequest): Promise<Response> => {
2210
const rawParams = Object.fromEntries(

‎packages/web/src/features/git/listCommitsApi.ts‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,13 @@ import { sew } from '@/actions';
22
import { invalidGitRef, notFound, ServiceError, unexpectedError } from '@/lib/serviceError';
33
import { withOptionalAuthV2 } from '@/withAuthV2';
44
import { getRepoPath } from '@sourcebot/shared';
5+
import { z } from 'zod';
56
import { simpleGit } from 'simple-git';
67
import { toGitDate, validateDateRange } from './dateUtils';
8+
import { commitSchema } from './schemas';
79
import { isGitRefValid } from './utils';
810

9-
export interface Commit {
10-
hash: string;
11-
date: string;
12-
message: string;
13-
refs: string;
14-
body: string;
15-
author_name: string;
16-
author_email: string;
17-
}
11+
export type Commit = z.infer<typeof commitSchema>;
1812

1913
export interface SearchCommitsResult {
2014
commits: Commit[];

‎packages/web/src/features/git/schemas.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,3 +64,25 @@ const fileDiffSchema = z.object({
6464
export const getDiffResponseSchema = z.object({
6565
files: z.array(fileDiffSchema).describe('The list of changed files.'),
6666
});
67+
68+
export const listCommitsQueryParamsSchema = z.object({
69+
repo: z.string().describe('The fully-qualified repository name.'),
70+
query: z.string().optional().describe('Filter commits by message content (case-insensitive).'),
71+
since: z.string().optional().describe('Return commits after this date. Accepts ISO 8601 or relative formats (e.g. `30 days ago`).'),
72+
until: z.string().optional().describe('Return commits before this date. Accepts ISO 8601 or relative formats.'),
73+
author: z.string().optional().describe('Filter commits by author name or email (case-insensitive).'),
74+
ref: z.string().optional().describe('The git ref (branch, tag, or commit SHA) to list commits from. Defaults to `HEAD`.'),
75+
path: z.string().optional().describe('Restrict commits to those that touch this file path.'),
76+
page: z.coerce.number().int().positive().default(1),
77+
perPage: z.coerce.number().int().positive().max(100).default(50),
78+
});
79+
80+
export const commitSchema = z.object({
81+
hash: z.string().describe('The full commit SHA.'),
82+
date: z.string().describe('The commit date in ISO 8601 format.'),
83+
message: z.string().describe('The commit subject line.'),
84+
refs: z.string().describe('Refs pointing to this commit (e.g. branch or tag names).'),
85+
body: z.string().describe('The commit body (everything after the subject line).'),
86+
author_name: z.string(),
87+
author_email: z.string(),
88+
});

0 commit comments

Comments
 (0)