OpenAPI spec at /api/docs with a Scalar viewer, opt-in via FEAT_API_DOCS

scripts/openapi/build-spec.ts

@@ -140,6 +140,33 @@ export function buildSpec({ routes, fileContents, annotationsByPath, isPublicFn,
 					required: true,
 					content: { 'application/json': { schema: miniSchemaToOpenApi(annotation.body), example } }
 				};
+			} else if (annotation?.bodyRaw) {
+				// A non-JSON raw body (e.g. application/x-tar): binary string schema.
+				const schema: Record<string, unknown> = { type: 'string', format: 'binary' };
+				if (annotation.bodyRaw.description) schema.description = annotation.bodyRaw.description;
+				requestBody = {
+					required: true,
+					content: { [annotation.bodyRaw.mediaType]: { schema } }
+				};
+			} else if (annotation?.bodyMultipart) {
+				// A multipart/form-data body with a single (possibly array) file field.
+				const mp = annotation.bodyMultipart;
+				const fieldSchema: Record<string, unknown> = mp.array
+					? { type: 'array', items: { type: mp.type === 'binary' ? 'string' : mp.type, format: mp.type === 'binary' ? 'binary' : undefined } }
+					: { type: mp.type === 'binary' ? 'string' : mp.type, format: mp.type === 'binary' ? 'binary' : undefined };
+				if (mp.description) fieldSchema.description = mp.description;
+				requestBody = {
+					required: true,
+					content: {
+						'multipart/form-data': {
+							schema: {
+								type: 'object',
+								properties: { [mp.field]: fieldSchema },
+								...(mp.required ? { required: [mp.field] } : {})
+							}
+						}
+					}
+				};
 			} else if (['POST', 'PUT', 'PATCH'].includes(method) && analysis.bodyFields.length > 0) {
 				const properties = Object.fromEntries(analysis.bodyFields.map((f) => [f, { type: 'string' }]));
 				requestBody = {

scripts/openapi/lib.ts

@@ -66,6 +66,11 @@ export interface HandlerAnnotation {
 	path: Record<string, ParamAnnotation>;
 	body?: MiniSchema;
 	bodyExample?: unknown;
+	/** A non-JSON raw request body, e.g. `body-raw: application/x-tar The image tar`. */
+	bodyRaw?: { mediaType: string; description: string };
+	/** A multipart/form-data body: one file field, e.g.
+	 *  `body-multipart: files:binary[]! One or more files`. */
+	bodyMultipart?: { field: string; type: string; array: boolean; required: boolean; description: string };
 	responses: Record<string, ResponseAnnotation>;
 	/** Raw block text, kept only for --check's orphan-block diagnostics. */
 	raw: string;
@@ -217,6 +222,14 @@ export function parseMiniSchema(str: string): MiniSchema {
 	function parseType(): MiniSchema {
 		skipWs();
 		if (s[i] === '{') return parseObject();
+		if (s[i] === '[') {
+			// bracket array form: [T]
+			i++;
+			const items = parseType();
+			skipWs();
+			if (s[i] === ']') i++;
+			return { kind: 'array', items };
+		}
 		if (s.slice(i, i + 6) === 'array<') {
 			i += 6;
 			const items = parseType();
@@ -226,6 +239,9 @@ export function parseMiniSchema(str: string): MiniSchema {
 		}
 		const start = i;
 		while (i < s.length && /[a-zA-Z0-9_]/.test(s[i])) i++;
+		// Guarantee forward progress: an unrecognized char (not a word, brace, or
+		// bracket) must still advance i, or the parseObject loop spins forever.
+		if (i === start) i++;
 		const word = s.slice(start, i) || 'string';
 		if (word === 'integer' || word === 'number' || word === 'boolean' || word === 'string') return { kind: word };
 		return { kind: 'string' };
@@ -374,6 +390,27 @@ export function parseAnnotations(content: string): Partial<Record<HttpMethod, Ha
 				}
 				continue;
 			}
+			if (key === 'body-raw') {
+				// `body-raw: <media-type> <description>` - a non-JSON raw body.
+				const rm = rawValue.match(/^(\S+)\s*(.*)$/);
+				if (rm) annotation.bodyRaw = { mediaType: rm[1], description: rm[2].trim() };
+				continue;
+			}
+			if (key === 'body-multipart') {
+				// `body-multipart: <field>:<type>[]? [!] <description>` - a multipart body.
+				const mm = rawValue.match(/^([a-zA-Z0-9_]+)\s*:\s*([a-zA-Z0-9_]+)(\[\])?(!)?\s*(.*)$/);
+				if (mm) {
+					const [, field, type, array, required, description] = mm;
+					annotation.bodyMultipart = {
+						field,
+						type,
+						array: !!array,
+						required: !!required,
+						description: description.trim()
+					};
+				}
+				continue;
+			}
 			const respMatch = key.match(/^resp-(\d{3})(-desc|-example)?$/);
 			if (respMatch) {
 				const [, code, suffix] = respMatch;