Bruno

Setup

Set up Fumastudio CLI for documenting your .bru collections.

npx @trythis/fuma-content build ./collections --bru-env Local --bruno

Server & Auth definition

At the root of your collections directory, you must define a folder.schema.ts file. This file declares shared server configuration and authentication schemes that apply to all nested requests.

import { v } from "@trythis/js-schema";

export const servers = v.server("{{protocol}}//{{baseUrl}}").vars({
	protocol: v.string().enum(["http:", "https:"]).default("https:"),
	baseUrl: v
		.string()
		.enum(["localhost:3000", "api.vercel.com"])
		.default("api.vercel.com"),
});

export const bearerAuth = v.bearerAuth();

• servers defines one or more base URLs that requests can reference using {{server}} Read more.

• .vars() declares the variables used inside the server template

• bearerAuth is automatically picked up & linked to requests that reference it Read more.

Requests

Each .bru file can (and should) be paired with a corresponding .schema.ts file describing its request and response shape. Fumastudio uses js-schema, a small DSL that maps 1:1 to JSON Schema while keeping a Zod-like authoring experience. The file name must match the .bru file exactly.

meta {
  name: create_a_new_project
  type: http
  seq: 1
}

post {
  url: {{server}}/v11/projects
  body: json
  auth: none
}

params:query {
  teamId: team_1a2b3c4d5e6f7g8h9i0j1k2l
  slug: my-team-url-slug
}

headers {
  Authorization: Bearer {{token}}
  Accept: Application/json
}

body:json {
  {
    "name": "fumastudio_docs"
  }
}

Required exports

Each *.schema.ts file is statically analyzed. The following exports are convention-based and drive how documentation is rendered.

// High-level description and title for the request
export const info = v.string();

// Shape of query parameters (params:query)
export const paramsQuery = v.object({});

// Shape of path parameters (params:path)
export const paramsPath = v.object({});

// JSON request body (body:json)
export const requestBody = v.object({});

export const responseBody = v.reply({
	ok: v.json({}),          // HTTP 200 JSON response
	forbidden: v.text(""),   // Example non-JSON response (e.g. 403 / 500)
});