Merge pull request #293 from ganesh-bruno/docs/aos

OAS spec revamp

Author: ganesh-bruno

public/screenshots/open-api/export-api-spec.webp

@@ -1,3 +1,6 @@
 export default {
-  "overview": "Overview"
-} 
+  "overview": "Overview",
+  "importOAS": "Import an OpenAPI Spec",
+  "exportOAS": "Export a Collection as OpenAPI Spec",
+  "createOAS": "Create an OpenAPI Spec"
+}

public/screenshots/open-api/import-collection-oas.webp

@@ -0,0 +1,45 @@
+import { Callout } from "nextra/components";
+import PremiumBadge from "@/components/premium-badge";
+
+# Create OpenAPI Specification (OAS)
+
+Bruno provides a powerful interface for creating and managing OpenAPI Specifications (OAS). You can either design a new specification from scratch and view one as existing Open API spec.
+
+## Viewing Existing OAS Files
+
+You can view and interact with existing OAS files in Bruno using a SwaggerUI-like interface:
+
+1. Open Bruno and Go to context menu (three dots)
+2. Select **Open API Spec** from dropdown
+
+![open-open-api](/screenshots/open-api/open-api-spec.webp)
+
+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](/screenshots/open-api/view-oas-file.webp)
+
+## Creating New OAS Files
+
+1. Open Bruno and Go to context menu (three dots)
+2. Select **Create API Spec**  from dropdown
+
+![create-open-api](/screenshots/open-api/create-api-spec.webp)
+
+3. Choose a name and location for your specification
+
+![location-open-api](/screenshots/open-api/select-api-spec-location.webp)
+
+4. Click on **Create** to generate OAS file.
+
+
+## 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](/screenshots/open-api/write-api-spec.webp)

public/screenshots/open-api/open-api-spec.webp

@@ -0,0 +1,69 @@
+import { Callout } from "nextra/components";
+
+# Export to OpenAPI Specification (OAS)
+
+Bruno allows you to export your collections as OpenAPI Specification (OAS) files, enabling you to share your API definitions with other tools and team members. This feature helps maintain consistency across your API documentation and development workflow.
+
+<Callout type="info">
+Bruno exports collections in OpenAPI Specification (OAS) V3 format, which is widely supported by API tools and platforms.
+</Callout>
+
+## Prerequisites
+
+Before exporting a collection, ensure:
+- Your collection is properly organized with clear request structures
+- All endpoints have appropriate HTTP methods defined
+- Request parameters and headers are properly configured
+
+### Exporting to a File
+
+1. Open Bruno and navigate to your collection
+2. Click on the context menu (three dots) in the collections panel
+3. Select **Share** from the dropdown menu
+
+![collection-settings](/screenshots/git-integration/share-collection/1-share-collection-overview.webp)
+
+4. Choose **OpenAPI Specification** option
+
+![ExportModal](/screenshots/get-started/import-export/export_collection/2-export-options.webp)
+
+5. Enter name of your file and location.
+6. Click **Create**
+
+
+## Example Exported Structure
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Example API
+  version: 1.0.0
+  description: API documentation exported from Bruno
+paths:
+  /users:
+    get:
+      summary: Get all users
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+```

public/screenshots/open-api/view-oas-file.webp

@@ -0,0 +1,52 @@
+import { Callout } from "nextra/components";
+
+# Import OpenAPI Specification (OAS)
+
+Bruno provides seamless integration with OpenAPI Specification (OAS), allowing you to import API definitions through both files and URLs. This feature enables you to quickly create collections in Bruno by leveraging existing OpenAPI documentation.
+
+<Callout type="info">
+Bruno supports importing OpenAPI Specification (OAS) V3 files only.
+</Callout>
+
+## Prerequisites
+
+Before importing an OpenAPI specification, ensure you have:
+- A valid OpenAPI V3 specification file (YAML or JSON format)
+- Or a publicly accessible URL containing the OpenAPI specification
+
+## Import Methods
+
+Bruno offers two ways to import OpenAPI specifications:
+
+1. **File Import**: Import from a local OpenAPI specification file
+2. **URL Import**: Import directly from a publicly accessible OpenAPI specification URL
+3. **Bruno Converter**: Programmatically convert an OAS file to a Bruno collection [by using our converter.](https://docs.usebruno.com/converters/overview)
+
+### Importing from a File
+
+1. Open Bruno and navigate to your collection
+2. Click on the context menu (three dots) in the collections panel
+3. Select **Import** from the dropdown menu
+4. Choose **OpenAPI V3 File** option
+
+![select-openapi-file](/screenshots/open-api/select-open-api.webp)
+
+5. Browse and select your OpenAPI specification file (`.yaml` or `.json`)
+6. Click **Import** to create the collection
+
+
+### Importing from a URL
+
+The import method for URL option is same as for URL but you need to select **OpenAPI V3 URL** as option and provide URL of OAS file which is publically available. 
+
+After, Importing the OAS file the sample collection will looks like this.
+
+![import-collection-oas](/screenshots/open-api/import-collection-oas.webp)
+
+## Example OpenAPI Specifications
+
+You can test the import functionality using these example OpenAPI specifications:
+
+1. **Petstore API**:
+   - URL: `https://petstore3.swagger.io/api/v3/openapi.json`
+   - Description: A sample API for a pet store

src/pages/open-api/_meta.js

@@ -4,60 +4,10 @@ import { Callout } from "nextra/components";
 
 # OpenAPI and Bruno
 
-Bruno allows you to work with OpenAPI Specification (OAS) files in a number of ways:
-
-- Creating a collection from an OAS file import
-- Exporting a collection as an OAS file <PremiumBadge />
-- Viewing and Designing an OAS file <PremiumBadge />
-
-## Creating a Collection from OAS Import
-
-<Callout type="info">Bruno supports importing OAS V3 files only</Callout>
-
-- Select Import
-- Choose OpenAPI V3 File
-
-![select-openapi-file](/screenshots/open-api/select-open-api.webp)
-
-- Select the file stored on your machine
-
-## Exporting a Collection as an OAS File <PremiumBadge />
-
-- Right-click on a collection and select Export
-
-![select-export](/screenshots/open-api/select-export.webp)
-
-- Choose OpenAPI Specification
-
-![select-openapi-from-export-menu](/screenshots/open-api/select-open-api-menu.webp)
-
-- Name your file and designate a location for it to be stored
+OpenAPI specification (AOS) is a standard formart for reading and describing the RESTful APIs. It provides a framework for defining apis, endpoints, auth, headers and etc. This format is easy to read and maintain API documentations. 
 
-![export-open-api](/screenshots/open-api/export-api-spec.webp)
-
-## Viewing and Designing an OAS file <PremiumBadge />
-
-If you've saved or otherwise have an OAS file on your machine, you can view the OAS in a SwaggerUI-esque manner by:
-
-- Selecting Open API Spec
-
-![open-open-api](/screenshots/open-api/open-api-spec.webp)
-
-- Choose the file name and location that you want to open
-
-This will then open the spec in a separate section of your Bruno sidebar called APIs.
-
-If you want to create an OAS file, you can:
-
-- Select Create API Spec
-  ![create-open-api](/screenshots/open-api/create-api-spec.webp)
-
-- Designate whether you want to create a Blank Spec, or generate it from an existing Bruno Collection
-
-![location-open-api](/screenshots/open-api/select-api-spec-location.webp)
-
-- Choose a name and location for the spec to be saved under.
-
-You will now have the scaffolding of an OAS that you can continue to design.
+Bruno allows you to work with OpenAPI Specification (OAS) files in a number of ways:
 
-![location-open-api](/screenshots/open-api/write-api-spec.webp)
+- [Creating a collection from an OAS file import](./importOAS.mdx)
+- [Exporting a collection as an OAS file](./exportOAS.mdx) <PremiumBadge />
+- [Viewing and Designing an OAS file](./createOAS.mdx) <PremiumBadge />