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! 🙏

[karenetheridge]

We could potentially nest under /paths:

...
paths:
  /x:
    ./y:
      get: ...
    ./z:
      get: ...

which would be equivalent to, in 3.x:

...
paths:
  /x/y:
    get: ...
  /x/z:
    get: ...

which correspond to these APIs:

• GET /x/y
• GET /x/z

This would be pretty straightforward to represent in the schema. Just add this to the path-item definition:

$defs:
  ...
  path-item:
    properties:
      existing definitions... (parameters, additionalOperations, legacy method names)
    patternProperties:
      '^\./':
        $ref: '$defs/path-item-or-ref'

(edited: okay that's not quite right, as we only want this under /paths, not any path-item e.g. in //components, but fixing this can be left as an exercise for the reader, or for future-me.)

[karenetheridge]

should I submit this as a feature request?

You just did! :)

[vaibhavshah08]

Yeah
Thanks for replying and upvoting it will help a lot

[ralfhandl]

OpenAPI 3.2 will add a parent field to the Tag Object which essentially is Option 1 of your potential solutions.

[vaibhavshah08]

Sure thanks