Can we create a subfolder like structure? to display it on readme.io

[vaibhavshah08]

How to Create Hierarchical Folder Structure in OpenAPI Documentation?

🤔 Question

I'm working with a large OpenAPI specification (40+ endpoints) and trying to organize my documentation with a hierarchical folder structure in ReadMe. I want to achieve something like this in the sidebar:

📁 User Management
├── 📁 Users
│   ├── 📄 Create User
│   ├── 📄 List All Users
│   ├── 📄 Get User by ID
│   └── 📁 Authentication
│       ├── 📄 User Login
│       ├── 📄 Refresh Token
│       └── 📄 Logout
├── 📁 Roles & Permissions
│   ├── 📄 Create Role
│   ├── 📄 Assign Permissions
│   └── 📄 List User Roles
└── 📁 Profile Management
    ├── 📄 Update Profile
    ├── 📄 Change Password
    └── 📄 Upload Avatar

📁 E-commerce
├── 📁 Products
│   ├── 📄 Create Product
│   ├── 📄 List Products
│   ├── 📄 Update Product
│   └── 📁 Categories
│       ├── 📄 Create Category
│       ├── 📄 List Categories
│       └── 📄 Get Products by Category
├── 📁 Orders
│   ├── 📄 Create Order
│   ├── 📄 Get Order Status
│   └── 📁 Order Management
│       ├── 📄 Update Order Status
│       ├── 📄 Cancel Order
│       └── 📄 Process Refund
└── 📁 Shopping Cart
    ├── 📄 Add to Cart
    ├── 📄 View Cart
    └── 📄 Remove from Cart

Is this possible with ReadMe's current OpenAPI implementation?

🔍 What I've Already Tried

Attempt 1: Hierarchical Tag Names

tags:
  - name: "User Management > Users"
  - name: "User Management > Users > Authentication"
  - name: "User Management > Roles & Permissions"
  - name: "E-commerce > Products"
  - name: "E-commerce > Products > Categories"
  - name: "E-commerce > Orders"

Result: Creates flat tags with > in the name, no nesting

Attempt 2: Tag Groups (x-tagGroups)

x-tagGroups:
  - name: User Management
    tags:
      - Users
      - User Authentication
      - Roles & Permissions
      - Profile Management
  - name: E-commerce
    tags:
      - Products
      - Product Categories
      - Orders
      - Shopping Cart

Result: Groups tags but still flat structure within groups

Attempt 3: Path-based Organization

Tried organizing file references in nested folders:

paths:
  /users/auth/login:
    $ref: ./paths/UserManagement/Users/Authentication/post-login.yaml
  /products/categories:
    $ref: ./paths/Ecommerce/Products/Categories/get-categories.yaml

Result: Works for file organization but doesn't affect ReadMe sidebar structure

💭 Current Environment

• ReadMe: Latest version
• OpenAPI: 3.0.0
• Format: YAML
• API Size: 40+ endpoints across 8 main categories

❓ My Questions

1. Does ReadMe support nested/hierarchical folder structures for OpenAPI imports?

2. If yes, what's the correct way to implement this?

   • Are there specific OpenAPI extensions?
   • Should I use a particular tag structure?
   • Is there documentation I missed?

3. If no, is this feature on ReadMe's roadmap?

🎯 Why I Need This

• Large API: 40+ endpoints become difficult to navigate in flat structure
• Logical Grouping: Related endpoints (like user authentication under users, or product categories under products) should be grouped
• Developer Experience: Users expect intuitive folder-like navigation similar to REST API explorers
• Professional Appearance: Clean, organized documentation

💡 Potential Solutions (If Feature Doesn't Exist)

If this isn't currently supported, I'd love to see:

Option 1: Enhanced Tag System

tags:
  - name: "User Authentication"
    x-readme-parent: "Users"
    x-readme-folder: true

Option 2: Folder Extension

x-readme-folders:
  - name: "User Management"
    children:
      - name: "Users"
        children:
          - name: "Authentication"

Option 3: Auto-inference from Paths

Automatically create folders based on URL structure:

/users/auth/login → Users > Authentication > Login
/products/categories → Products > Categories
/orders/management/cancel → Orders > Management > Cancel

---

Can anyone help me figure out if this is possible, or should I submit this as a feature request?

Looking forward to your insights! 🙏