DOCSEARCHbyAlgolia
Submit Docs

Fern API

repository·main·Indexed 25 days ago

https://github.com/fern-api/fern

Documentation for the Fern CLI and its ecosystem, featuring the Generator Migration System for automating generators.yml updates, architecture documentation for fern-cli-sdk using Mermaid diagrams, and internal packages such as @fern-api/openapi-pruner.

Tokens
140.4K
Snippets
406
Records
679
Agent score
86%

What's inside fern

  1. Overview of @fern-api/generator-migrations

    main
    The @fern-api/generator-migrations package is a unified migration package for all Fern generator configurations. It is consumed automatically by the Fern CLI during generator upgrades. When a user runs fern generator upgrade, the CLI downloads the latest version of this package and applies relevant migrations to transform the user's generators.yml configuration.

  2. Overview of fern-cli-sdk architecture

    main

    The fern-cli-sdk is a Rust-based library and binary template designed to transform API schemas into dynamic Command Line Interfaces (CLIs) at compile time. Instead of a separate code generation step, the schema is embedded directly into the binary using include_str!, parsed at process startup, and used to construct a clap::Command tree in memory.

    Supported protocols include:

    • OpenAPI: Converts YAML specs to a RestDescription and clap tree, utilizing Fern's x-fern-* extensions.
    • GraphQL: Derives the command tree from Query and Mutation types using introspection JSON.
    • AsyncAPI: Supports AsyncAPI 2.6 YAML/JSON, focusing on channel/operation models (rejects non-2.6.x versions and non-WebSocket server protocols).

    The system is designed for protocol isolation, ensuring customers only receive the specific protocol logic they require (e.g., only OpenAPI or only GraphQL).

  3. Understand the Fern Generator Migration System

    main
    The Generator Migration System allows Fern CLI to automatically transform generators.yml configuration during version upgrades. When you run fern generator upgrade, the CLI detects version changes, downloads the @fern-api/generator-migrations package to a local cache (~/.fern/migration-cache/), and applies a sequence of migrations to your configuration files. This prevents breaking changes in generator schemas from requiring manual user intervention.

  4. Explore the fern-cli-sdk architecture documentation

    main

    The docs/architecture/ directory contains the system architecture documentation for fern-cli-sdk. Use these resources to understand the system design, visual diagrams, and decision history:

    • System Architecture: See ARCHITECTURE.md for the arc42-lite system architecture document.
    • Visual Diagrams: The diagrams/ directory contains C4-style Mermaid diagrams (context, container, components, and runtime). Refer to diagrams/README.md for details.
    • Architectural Decisions: The decisions/INDEX.md file provides an index of formal ADRs (Architectural Decision Records) and implicit decisions.
    • Architecture Changelog: CHANGELOG-ARCH.md tracks architecture-shaping changes.
    • Documentation Automation: The automation/ directory contains the playbook and configuration for the agent that maintains this directory.

  5. Understand the Fern CLI Generator scope and inputs

    main

    The Fern CLI generator is a project scaffolder designed for engineers building fernapi/fern-cli. Its primary purpose is to take the Fern Intermediate Representation (IR) and a customer's generators.yml configuration to emit a buildable Rust project and open a Pull Request.

    Key Characteristics

    • One CLI binary per IR: The generator runs once per Fern API invocation. If a customer has multiple APIs, they receive multiple generator invocations and multiple CLI binaries.
    • Multi-binding: A single CLI can support multiple transport classes (e.g., HTTP services, WebSocket channels, and gRPC services) if they are contained within the same IR.
    • State Management: The generator does not track customer state. Instead, customer customizations are preserved across regenerations using Fern Replay's 3-way merge, where customizations live inline in main.rs.

    Required Inputs

    1. Fern IR: The intermediate representation used as the source of truth.
    2. generators.yml config: A minimal configuration file containing:
      • cli-name
      • display-name

  6. Understand the fern-cli-sdk architecture

    main

    The fern-cli-sdk is a Rust crate designed to power CLI tools for various API protocols. It is structured as a single Cargo workspace member that exposes a public API surface via the fern_cli_sdk library.

    Key architectural components include:

    • Public API: Re-exports CliApp, AppContext, HandlerFn, and building-block modules.
    • Binary Targets: Automatically discovered under src/bin/<name>/main.rs. Each binary typically wires a specification, authentication, and optional custom commands, then calls .run().
    • Protocol Paths: Separate, isolated implementations for OpenAPI, GraphQL, and AsyncAPI to ensure protocol-specific logic (like parsing and execution) remains decoupled while sharing common infrastructure.

  7. Use the test-x-fern-global-parameters-extension CLI

    main

    The CLI follows a subcommand pattern where every API resource is a subcommand. To use a specific method on a resource, use the syntax: test-x-fern-global-parameters-extension <resource> <method>.

    To see available methods for a specific resource, run: test-x-fern-global-parameters-extension <resource> --help.

    You can provide request parameters using individual flags or by passing a JSON object via the --json flag.

    Example: Calling an API endpoint with JSON

    test-x-fern-global-parameters-extension <resource> <method> --json '{"key": "value"}'
    test-x-fern-global-parameters-extension <resource> <method> --json '{"key": "value"}'

  9. Use the Seed Java Client

    main

    To use the library, instantiate a SeedFileDownloadClient using the builder pattern and call the desired service methods.

    package com.example.usage;

import com.seed.fileDownload.SeedFileDownloadClient;

public class Example {
    public static void main(String[] args) {
        SeedFileDownloadClient client = SeedFileDownloadClient
            .builder()
            .build();

        client.service().simple();
    }
}
    package com.example.usage;

import com.seed.fileDownload.SeedFileDownloadClient;

public class Example {
    public static void main(String[] args) {
        SeedFileDownloadClient client = SeedFileDownloadClient
            .builder()
            .build();

        client.service().simple();
    }
}

  10. Use Webhook Audience Test CLI subcommands and JSON bodies

    main

    The CLI follows a subcommand pattern: webhook-audience-test <resource> <method>. You can provide request parameters using individual flags or by passing a JSON object via the --json flag.

    webhook-audience-test <resource> <method> --json '{"key": "value"}'
    webhook-audience-test <resource> <method> --json '{"key": "value"}'

  12. Install the Versioned Store CLI

    main

    You can install the Versioned Store CLI using a shell script for macOS/Linux, a PowerShell script for Windows, or by building from source using Rust.

    ### Shell (macOS / Linux)
```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/<org>/<repo>/releases/latest/download/versioned-store-installer.sh | sh

    PowerShell (Windows)

    powershell -ExecutionPolicy ByPass -c "irm https://github.com/<org>/<repo>/releases/latest/download/versioned-store-installer.ps1 | iex"

    Build from source

    Install the Rust toolchain and run:

    cargo build --release
./target/release/versioned-store --help