NoEgo Framework

Configuration

Create a stitch.yaml file to specify which OpenAPI files to combine:

stitch.yaml

stitch:
  - openapi/**/*.yaml

For more control, you can specify multiple patterns to include files in a specific order:

stitch.yaml

stitch:
  - openapi/base.yaml
  - openapi/auth/*.yaml
  - openapi/users/*.yaml
  - openapi/products/*.yaml

Order Matters

Files are processed in the order specified. Later files can override definitions from earlier files, so put your base configuration first.

Glob Patterns

Stitch uses glob patterns to match files. Here are common patterns you can use:

Pattern	Matches
*.yaml	All YAML files in the current directory
*/.yaml	All YAML files in any subdirectory
openapi/*/.yaml	All YAML files under the openapi directory
openapi/auth/*.yaml	All YAML files directly in openapi/auth
!**/internal.yaml	Exclude files named internal.yaml

How Stitching Works

During the build process, Stitch performs the following steps:

Pattern Resolution

Stitch expands all glob patterns and collects matching files in order.

YAML Parsing

Each file is parsed and validated as YAML.

Deep Merge

Files are deeply merged, combining paths, components, and other OpenAPI sections.

Reference Resolution

Internal $ref references are resolved and validated.

Output Generation

The final combined specification is produced for use by the application.

Example File Structure

A typical project structure when using Stitch:

project/
├── stitch.yaml
└── openapi/
    ├── base.yaml          # API info, servers, global config
    ├── auth/
    │   └── auth.yaml      # Authentication endpoints
    ├── users/
    │   └── users.yaml     # User management endpoints
    └── products/
        └── products.yaml  # Product endpoints

Base Configuration

openapi/base.yaml

# openapi/base.yaml
openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
servers:
  - url: http://localhost:3000

Route Definition

openapi/users/users.yaml

# openapi/users/users.yaml
paths:
  /users:
    get:
      summary: List users
      x-view: pages/users/list.svelte
      x-layout:
        - layout/app.svelte
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'

Validation

Stitch automatically validates the combined specification and reports errors:

Duplicate Path Detection

Warns when the same path is defined in multiple files.

Missing References

Errors when $ref points to non-existent schemas or components.

Schema Validation

Validates the final output against the OpenAPI 3.0 specification.

Common Use Cases

Modular API Design

Organize endpoints by domain (users, products, orders) for better maintainability.

Team Collaboration

Different teams can work on separate API files without merge conflicts.

Frontend Routes

Combine OpenAPI files that define Svelte page routes with x-view extensions.

Shared Components

Define common schemas in base files and reference them across all API files.

Back to Stitch Overview