How Do You Generate and Host API Docs From Bruno?

If you use Bruno, the core benefit is clear: your API collections live as plain .bru files in your Git repo, version-controlled alongside the application code, with no cloud account required. It is an offline-first API client workflow that keeps request data close to the codebase.

Try Apidog today

The limitation shows up when someone asks: “Where are the API docs? Can you send me a link?” Bruno is useful for sending requests and storing collections, but it is not designed to publish a hosted documentation portal. This guide explains what Bruno provides, where it stops, and how to generate shareable API documentation from an OpenAPI spec when your team needs a real URL.

What developers need from API documentation

Before choosing a documentation workflow, define what the output needs to do.

A usable API documentation setup usually needs three things:

• A shareable URL
  
  Frontend developers, QA engineers, partners, and external consumers should be able to open the docs without cloning a repo or installing an API client.

• Docs that stay in sync with the API contract
  
  If the docs drift from the actual API, they become actively misleading. The documentation should be generated from the same source of truth as the API contract.

• An interactive request runner
  
  Static endpoint descriptions help, but docs become much more useful when users can send requests from the page using documented parameters, headers, auth, and sample payloads.

If your docs satisfy all three, they can become the team’s API reference. If not, developers usually fall back to asking the API owner directly.

What Bruno provides for documentation

Bruno does support some documentation-friendly workflows.

Its .bru files are plain text, so developers can inspect requests directly in the repository. A request file can show the method, URL, headers, and body. Bruno also supports a docs block per request and a Markdown documentation view inside the app.

That means you can document an endpoint close to the request itself:

meta {
  name: Get user
  type: http
}

get {
  url: {{baseUrl}}/users/{{userId}}
}

headers {
  Authorization: Bearer {{token}}
}

docs {
  # Get user

  Returns a user by ID.

  Requires a valid bearer token.
}

Because the collection is stored in Git, these notes can be reviewed in pull requests with the rest of the API changes. For an internal team that already works in the repo, this can be a practical lightweight documentation approach.

Where Bruno stops

The gap is publishing.

Bruno does not include a built-in hosted documentation portal that automatically turns your collection into a public website. There is no native “publish docs” workflow that creates a stable URL, supports a custom domain, and lets API consumers try requests from the browser.

In practice, this means the in-app docs are mainly useful for people who:

1. Have Bruno installed.
2. Have cloned the collection.
3. Know where to look inside the project.

That is usually not the audience that needs API docs the most.

Common workarounds include:

• Exporting an OpenAPI file and generating static docs separately.
• Building a documentation site in CI.
• Maintaining a README.md by hand.
• Copying endpoint details into another docs platform.

These approaches can work, but they introduce another pipeline and another place where the API description can drift.

Use docs-as-code instead

A cleaner workflow is to treat documentation as a generated output of your API specification.

In a docs-as-code workflow, your API is described once in a machine-readable contract such as OpenAPI. That spec lives in Git, gets reviewed in pull requests, and becomes the source of truth for:

• Documentation
• Mock servers
• Tests
• Client SDKs
• API examples

The key idea is simple:

OpenAPI spec -> generated docs
OpenAPI spec -> mock server
OpenAPI spec -> tests
OpenAPI spec -> client references

You no longer maintain documentation as a separate artifact. If the contract changes, the generated documentation changes with it.

Bruno already aligns with part of this mindset by keeping collections in Git. The missing piece is the publishing workflow.

Generate and host docs from your spec

This is where Apidog fits the workflow. It uses a spec-centered approach and adds hosted, interactive API documentation generated from your API definition.

With an OpenAPI spec, you can generate documentation that is:

• Hosted at a shareable URL.
• Available without installing an API client.
• Configurable for public, private, or protected access.
• Optionally mounted on a custom domain such as docs.yourcompany.com.
• Interactive, with a built-in “try it” experience.
• Generated from the API spec instead of manually copied content.

The implementation model is:

OpenAPI spec
   ↓
Import into Apidog
   ↓
Configure documentation visibility
   ↓
Publish
   ↓
Share the docs URL

Walkthrough: publish API docs from an OpenAPI spec

Here is the practical flow.

Step	Action	Result
1	Import or write your OpenAPI spec in Apidog	Endpoints, schemas, and examples are loaded
2	Open the project documentation settings	Generated docs are ready to configure
3	Choose visibility	Docs can be public, private, or protected
4	Optionally configure a custom domain	Docs can live under your own domain
5	Publish	A hosted documentation site is created
6	Share the URL	Consumers can read docs and run “try it” requests

If your OpenAPI file is already in Git, keep it there. Review contract changes through pull requests, then publish documentation from the updated spec.

A typical repository layout might look like this:

api/
  openapi.yaml
  README.md
src/
  ...

When the API changes, update the spec first:

paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User found

Then regenerate or republish the docs from the same spec.

What if you already use Bruno?

You do not have to abandon Bruno collections immediately.

If your current workflow starts in Bruno, the practical path is:

1. Keep your existing Bruno collection.
2. Export or convert the collection to OpenAPI.
3. Review the generated OpenAPI spec.
4. Import the spec into a documentation tool.
5. Publish the hosted docs.

The important step is moving the public documentation source of truth to the API spec. Once the spec is accurate, the documentation can be generated from it.

Keep documentation in sync

A documentation URL only helps if it stays accurate.

The usual failure mode is:

API changes -> code ships -> docs are forgotten

A spec-driven workflow changes that to:

API contract changes -> spec is reviewed -> docs are generated from the spec

For example:

• Add a response field in the schema, and it appears in the docs.
• Mark an endpoint as deprecated, and the docs show that status.
• Update an auth requirement, and the interactive request panel reflects it.
• Add examples to the spec, and consumers see usable request and response samples.

This reduces documentation maintenance to contract maintenance. The same work that keeps the API spec correct also keeps the docs correct.

FAQ

Can Bruno generate and host public API documentation?

Bruno provides readable .bru files and an in-app Markdown documentation view. Those files can be reviewed in Git and used as internal documentation.

However, Bruno does not include a built-in hosted public documentation portal with a shareable URL and interactive “try it” experience. To publish public docs, teams usually export a spec and use a separate documentation generator or platform.

How do I create a shareable API docs URL?

Describe your API in an OpenAPI spec, then publish documentation from that spec.

A typical workflow is:

1. Create or import the OpenAPI spec.
2. Generate docs from the spec.
3. Configure visibility.
4. Optionally attach a custom domain.
5. Publish and share the URL.

Do I need to stop using Bruno?

No. You can continue using Bruno for local request workflows while using an OpenAPI spec as the source for hosted documentation.

If you already have Bruno collections, convert them to OpenAPI first, review the generated spec, and publish docs from there.

What is the main advantage of generating docs from OpenAPI?

The docs stay tied to the API contract. Instead of maintaining a separate hand-written document, you update the spec and generate the docs from it. This reduces drift and makes the documentation workflow easier to review in Git.