(feature): Add ApiVersionSchema type

[amckinney]

Feature

This proposes a new ApiVersionSchema type which is used to configure an API-wide version header enum. Users can configure this with the following:

# api.yml
version:
  header: X-API-Version
  default: "1.0.0"
  values:
    - "1.0.0-alpha"
    - "1.0.0-beta"
    - "1.0.0"

Implementation

Given that the version header has a few more restrictions than general HTTP headers and enum type declarations, this proposes a few new YAML schema types for the VersionDeclarationSchema. Regardless, these schemas are still capable of mapping into the same IR types (i.e. http.HttpHeader and types.EnumTypeDeclaration).

We also plan to support default values on enum type declarations and type references, so this defines the default value there.

Behavior

In TypeScript, the user will receive a special Version type like so:

// version.ts
type Version = "1.0.0-alpha" | "1.0.0-beta" | "1.0.0";

If a default value is configured, that X-API-Version header is sent on every request. Otherwise, the version header is treated as a required global header, which is specified on the client constructor.

[github-actions]

🌿 Preview your docs: https://fern-preview-68421ec4-fad4-43a9-a4a8-62e7977fa437.docs.buildwithfern.com