Working with Multi Part Specs

📄 Working with Multi-Part Specifications

This guide explains how to split large OpenAPI specifications across multiple files and use the spec merge and spec split CLI commands.

🌟 Overview

Large APIs with many endpoints become difficult to manage in a single YAML file. Multi-part specifications let teams work on different API domains independently while the generator automatically merges them at build time.

MyApi.yaml                    # Base file (info, servers, security)
MyApi_Accounts.yaml           # Account endpoints + schemas
MyApi_Users.yaml              # User endpoints + schemas
MyApi_Common.yaml             # Shared schemas (PaginatedResult, Error)

📂 File Naming Convention

Part files follow the pattern {BaseName}_{PartName}.yaml:

Base File	Part Files
MyApi.yaml	MyApi_Accounts.yaml, MyApi_Users.yaml, MyApi_Common.yaml
PetStore.yaml	PetStore_Pets.yaml, PetStore_Store.yaml

The generator auto-discovers part files by this naming convention.

🔧 Setting Up Multi-Part Specs

1. Split an Existing Spec

atc-rest-api-gen spec split \
  -s MyApi.yaml \
  -o ./specs/ \
  --strategy FirstPathSegment

Split strategies:

Strategy	Description
FirstPathSegment	Groups by first path segment (/users/* -> Users part)
OpenApiTag	Groups by operation tag

2. Base File Structure

After splitting, the base file contains shared elements:

# MyApi.yaml (base)
openapi: 3.1.1
info:
  title: My Demo API
  version: 1.0.0
servers:
  - url: /api/v1
security:
  - BearerAuth: []

# Marker for multi-part configuration
x-multipart:
  enabled: true
  discovery: auto

paths: {}
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

3. Part File Structure

Each part file contains only its domain's paths and schemas:

# MyApi_Users.yaml (part)
paths:
  /users:
    get:
      operationId: listUsers
      tags: [users]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

  /users/{userId}:
    get:
      operationId: getUserById
      tags: [users]
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string

🔄 Merge Command

Merge part files back into a single spec (for validation or external tools):

atc-rest-api-gen spec merge \
  -s MyApi.yaml \
  -o merged-output.yaml

Merge Strategies

Configure how conflicts are handled in the marker file:

{
  "multiPartConfiguration": {
    "enabled": true,
    "discovery": "auto",
    "pathsMergeStrategy": "ErrorOnDuplicate",
    "schemasMergeStrategy": "ErrorOnDuplicate",
    "parametersMergeStrategy": "MergeIfIdentical",
    "tagsMergeStrategy": "AppendUnique"
  }
}

Strategy	Behavior
ErrorOnDuplicate	Fail if same path/schema defined in multiple parts
MergeIfIdentical	Allow duplicates only if definitions are identical
AppendUnique	Merge by appending unique entries

Explicit Part Lists

For non-standard naming, specify parts explicitly:

{
  "multiPartConfiguration": {
    "discovery": "explicit",
    "parts": [
      "specs/accounts-api.yaml",
      "specs/users-api.yaml",
      "specs/shared-schemas.yaml"
    ]
  }
}

⚙️ Build-Time Merging

The source generator automatically merges part files during build — no manual merge step needed:

1. Generator detects MyApi.yaml as the base file
2. Discovers MyApi_*.yaml part files in the same directory
3. Merges paths, schemas, parameters, and tags
4. Generates code from the merged document

💡 Tip: Run spec merge before committing to verify no merge conflicts.

📦 Sample Project

See sample/MultipartDemo/ for a working example with 6 part files across different API domains.

➡️ Next Steps

• Working with OpenAPI — YAML patterns and generated code
• Working with CLI — Full CLI command reference
• Marker Files — Configuration reference