> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebruno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create OpenAPI Specification (OAS)

Bruno can open an existing OpenAPI Specification (OAS) and create a new one. A new spec can start blank, be generated from a Bruno collection, or be fetched from a URL hosting an OpenAPI spec.

## Viewing Existing OAS Files

You can view and interact with existing OAS files in Bruno using a SwaggerUI-like interface:

1. Enable OpenAPI Spec feature from **Preferences** to start working with it.

![enable-openapi-spec](https://mintcdn.com/bruno-a6972042/bhHnFle6fniGMyOW/images/screenshots/open-api/enable-openapi-spec-settings.webp?fit=max\&auto=format\&n=bhHnFle6fniGMyOW\&q=85\&s=1d25e1c711e6f6924703ea6636137e9e)

2. Select **Open API Spec** from dropdown in left hand side menu.

![open-open-api](https://mintcdn.com/bruno-a6972042/bhHnFle6fniGMyOW/images/screenshots/open-api/create-open-option-spec.webp?fit=max\&auto=format\&n=bhHnFle6fniGMyOW\&q=85\&s=666f46ce33acb33e551cb417384629e3)

3. Browse and select your OAS file (`.yaml` or `.json`)
4. The specification will open in a dedicated section of your Bruno sidebar

![view-open-api](https://mintcdn.com/bruno-a6972042/bhHnFle6fniGMyOW/images/screenshots/open-api/after-import-openapi-spec.webp?fit=max\&auto=format\&n=bhHnFle6fniGMyOW\&q=85\&s=420cfd6474577f090f94db691e9a7bb0)

## Creating New OAS Files

1. In the sidebar, click **+** next to **API Specs**.
2. Select **Create API Spec**.

**Source** has three options: **Blank Spec**, **Bruno Collection**, and **Spec URL**. Every source includes **Name** and **Location**. **Location** is filled in for you: a named workspace uses its `apispec` folder, and the default workspace uses the default location from **Preferences** (or that workspace's `apispec` folder when no default location is set). Optionally, use **Browse** to select the location, then click **Create**.

| Source | Description |
| - | - |
| Blank Spec | Leave **Source** on **Blank Spec** and enter a **Name**. Bruno writes an empty `.yaml` file. |
| Bruno Collection | Select **Bruno Collection** to generate an OpenAPI 3 spec from the requests in a collection. |
| Spec URL | Select **Spec URL** and enter an `http` or `https` URL that returns an OpenAPI 3.x document (YAML or JSON). Bruno fetches the URL and checks that it is an OpenAPI 3.x specification. **Name** is filled from the spec's `info.title`. The saved file is `.json` when the response is JSON, and `.yaml` otherwise. |

### Blank Spec

Leave **Source** on **Blank Spec** and enter a **Name**. Bruno writes an empty `.yaml` file.

### Bruno Collection

Select **Bruno Collection** to generate an OpenAPI 3 spec from the requests in a collection.

**From workspace** lists the collections in the active workspace. Pick one from the dropdown. **Name** is filled from the collection name. When that collection has environments, an **Environment** field appears and the selected environment's variables are written into the spec.

![Create API Spec from a collection in the workspace](https://mintcdn.com/bruno-a6972042/S_s4VGJcZ-_gKII9/images/screenshots/v4/chores/create-api-spec-from-workspace-collection.webp?fit=max\&auto=format\&n=S_s4VGJcZ-_gKII9\&q=85\&s=733ee944a65cf862039da957dd9cb5ef)

**From filesystem** browses for a collection folder on disk. Select **From filesystem**, click the folder field, and choose a folder that contains `bruno.json` or `opencollection.yml`. **Name** is filled from the folder name.

### Spec URL

Select **Spec URL** and enter an `http` or `https` URL that returns an OpenAPI 3.x document (YAML or JSON). Bruno fetches the URL and checks that it is an OpenAPI 3.x specification. **Name** is filled from the spec's `info.title`. The saved file is `.json` when the response is JSON, and `.yaml` otherwise.

![Create API Spec from a hosted OpenAPI URL](https://mintcdn.com/bruno-a6972042/S_s4VGJcZ-_gKII9/images/screenshots/v4/chores/create-api-spec-from-spec-url.webp?fit=max\&auto=format\&n=S_s4VGJcZ-_gKII9\&q=85\&s=f385e51f52cead8f36bba487a1bc8d70)

## Editing Your OAS File

Once created, you can edit your OAS file in Bruno's built-in editor:

1. The editor provides syntax highlighting
2. Use the sidebar to navigate through different sections of your API
3. Add or modify endpoints, parameters, and responses
4. Include examples and descriptions for better documentation

![write-api-spec](https://mintcdn.com/bruno-a6972042/bKrHa_JvyAqCslj1/images/screenshots/open-api/write-api-spec.webp?fit=max\&auto=format\&n=bKrHa_JvyAqCslj1\&q=85\&s=79e36eaa551f71ccbf2a284d108ff725)
