Fern Docs.rtf

{\rtf1\ansi\ansicpg1252\cocoartf2820
\cocoatextscaling0\cocoaplatform0{\fonttbl\f0\fmodern\fcharset0 Courier;}
{\colortbl;\red255\green255\blue255;\red0\green0\blue0;}
{\*\expandedcolortbl;;\cssrgb\c0\c0\c0;}
\margl1440\margr1440\vieww11520\viewh8400\viewkind0
\deftab720
\pard\pardeftab720\partightenfactor0

\f0\fs26 \cf0 \expnd0\expndtw0\kerning0
\outl0\strokewidth0 \strokec2 # Welcome\
\
> Input OpenAPI. Output SDKs and Docs.\
\
<Note>\
  Our entire docs website (the one you're looking at right now!) is built using Fern. \
\
  [See the source Markdown.](https://github.com/fern-api/fern/blob/main/fern/pages/welcome.mdx?plain=1)\
</Note>\
\
## Products\
\
<Cards cols=\{3\}>\
  <Card title="API First Development" icon="fa-regular fa-pen" href="/learn/api-definition/introduction/what-is-an-api-definition">\
    Start with an API Definition\
  </Card>\
\
  <Card title="Docs" icon="fa-regular fa-browser" href="/learn/docs/getting-started/quickstart">\
    A beautiful documentation website\
  </Card>\
\
  <Card title="SDKs" icon="fa-brands fa-codepen" href="/learn/sdks/introduction/overview">\
    Idiomatic client libraries\
  </Card>\
</Cards>\
\
## Motivation\
\
<div>\
  Stripe, Twilio, and AWS have the resources to invest in internal tooling for developer\
  experience. They provide client libraries in multiple languages and developer documentation\
  that stays up-to-date.\
\
  We are building Fern to productize this process and make it accessible to all\
  software companies.\
</div>\
\
<ButtonGroup>\
  <Button href="https://buildwithfern.com/contact" intent="primary" rightIcon="arrow-right" large>\
    Schedule a demo with our team!\
  </Button>\
\
  <Button href="https://buildwithfern.com/showcase" minimal large>\
    View our showcase\
  </Button>\
</ButtonGroup>\
\
\
# What is an API Definition?\
\
> Describes the contract between the API provider and API consumer\
\
<Info>\
  An API Definition is a document that defines the structure of the API. It includes the **endpoints**,\
  **request and response schemas**, and **authentication** requirements.\
</Info>\
\
Fern integrates with several API definition formats:\
\
<AccordionGroup>\
  <Accordion title="OpenAPI (Swagger)">\
    Formerly known as Swagger, [OpenAPI](https://swagger.io/specification/) is the most popular API definition format.\
    OpenAPI can be used to document RESTful APIs and is defined in a YAML or JSON file.\
\
    Check out an example OpenAPI Specification for the Petstore API [here](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)\
\
    ```yaml maxLines=\{0\}\
    openapi: 3.0.2\
    tags:\
      - name: pet\
        description: Everything about your Pets\
    paths:\
      /pet:\
        post:\
          tags:\
            - pet\
          summary: Add a new pet to the store\
          description: Add a new pet to the store\
          operationId: addPet\
          requestBody:\
            description: Create a new pet in the store\
            required: true\
            content:\
              application/json:\
                schema:\
                  $ref: '#/components/schemas/Pet'\
              application/xml:\
                schema:\
                  $ref: '#/components/schemas/Pet'\
              application/x-www-form-urlencoded:\
                schema:\
                  $ref: '#/components/schemas/Pet'\
          responses:\
            '200':\
              description: Successful operation\
              content:\
                application/xml:\
                  schema:\
                    $ref: '#/components/schemas/Pet'\
                application/json:\
                  schema:\
                    $ref: '#/components/schemas/Pet'\
            '405':\
              description: Invalid input\
        components:\
          schemas:\
            Pet:\
              required:\
                - name\
                - photoUrls\
              properties:\
                id:\
                  type: integer\
                  format: int64\
                  example: 10\
                name:\
                  type: string\
                  example: doggie\
                category:\
                  $ref: '#/components/schemas/Category'\
                photoUrls:\
                  type: array\
                  xml:\
                    wrapped: true\
                  items:\
                    type: string\
                    xml:\
                      name: photoUrl\
                tags:\
                  type: array\
                  xml:\
                    wrapped: true\
                  items:\
                    $ref: '#/components/schemas/Tag'\
                    xml:\
                      name: tag\
                status:\
                  type: string\
                  description: pet status in the store\
                  enum:\
                    - available\
                    - pending\
                    - sold\
              xml:\
                name: pet\
              type: object\
    ```\
  </Accordion>\
\
  <Accordion title="AsyncAPI">\
    [AsyncAPI](https://v2.asyncapi.com/docs) is a specification for defining event-driven APIs. It is used to document APIs that use\
    WebSockets, MQTT, and other messaging protocols.\
\
    Check out an example AsyncAPI spec for a chat application below:\
\
    ```yaml maxLines=\{0\}\
    asyncapi: 2.0.0\
    info:\
      title: Chat server\
      version: 1.0.0\
\
    servers:\
      Production:\
        url: chat.com\
        protocol: ws\
\
    channels:\
      "/application":\
        bindings:\
          ws:\
            query:\
              type: object\
              properties:\
                apiKey:\
                  type: string\
                  description: The API key for the client\
                  minimum: 1\
            bindingVersion: 0.1.0\
        subscribe:\
          operationId: sendMessage\
          message:\
            $ref: '#/components/messages/SendMessage'\
        publish:\
          operationId: receiveMessage\
          message:\
            $ref: '#/components/messages/ReceiveMessage'\
\
    components:\
      messages:\
        SendMessage:\
          payload:\
            message: string\
        ReceiveMessage:\
          payload:\
            message: string\
            from: \
              type: string\
              description: The userId for the sender of the message\
    ```\
  </Accordion>\
\
  <Accordion title="Fern Definition">\
    The Fern Definition is our take on a simpler API definition format. It is designed with **best-practices**,\
    supports **both RESTful and event-driven APIs**, and is optimized for **SDK generation**.\
\
    <Note>\
      The Fern Definition is inspired from internal API Definition formats built at companies like\
      [Amazon](https://smithy.io/2.0/index.html), [Google](https://grpc.io/), [Palantir](https://blog.palantir.com/introducing-conjure-palantirs-toolchain-for-http-json-apis-2175ec172d32),\
      Twilio and Stripe. These companies **rejected** OpenAPI and built their own version.\
    </Note>\
\
    Check out an example Fern Definition below:\
\
    ```yaml maxLines=\{0\}\
    types:\
      MovieId: string\
\
      Movie:\
        properties:\
          id: MovieId\
          title: string\
          rating:\
            type: double\
            docs: The rating scale is one to five stars\
\
      CreateMovieRequest:\
        properties:\
          title: string\
          rating: double\
\
    service:\
      auth: false\
      base-path: /movies\
      endpoints:\
        createMovie:\
          docs: Add a movie to the database\
          method: POST\
          path: /create-movie\
          request: CreateMovieRequest\
          response: MovieId\
\
        getMovie:\
          method: GET\
          path: /\{movieId\}\
          path-parameters:\
            movieId: MovieId\
          response: Movie\
          errors:\
            - MovieDoesNotExistError\
\
    errors:\
      MovieDoesNotExistError:\
        status-code: 404\
        type: MovieId\
    ```\
  </Accordion>\
</AccordionGroup>\
\
## Why create an API Definition ?\
\
Once you have an API definition, Fern will use it as an input to generate artifacts\
like SDKs and API Reference documentation. Every time you update the API definition,\
you can regenerate these artifacts and ensure they are always up-to-date.\
\
<CardGroup cols=\{2\}>\
  <Card title="SDKs" icon="brands github">\
    Client libraries in multiple languages.\
  </Card>\
\
  <Card title="Documentation" icon="regular browser">\
    A Stripe-like API documentation website.\
  </Card>\
\
  <Card title="Postman Collection" icon=\{<img src="https://cdn.worldvectorlogo.com/logos/postman.svg" alt="Postman logo"/>\}>\
    A published Postman collection, with example request and responses.\
  </Card>\
\
  <Card title="Server Boilerplate" icon=\{<img src="https://cdn.worldvectorlogo.com/logos/fastapi-1.svg" alt="FastAPI logo" />\}>\
    Pydantic models for FastAPI or controllers for your Spring Boot application.\
  </Card>\
</CardGroup>\
\
\
# The Fern Folder\
\
> Describes the Fern folder structure\
\
Configuring fern starts with the `fern` folder. The fern folder contains your API definitions,\
generators, and your CLI version.\
\
## Directory structure\
\
When you run `fern init`, your Fern folder will be initialized with the following files:\
\
```bash\
fern/\
  \uc0\u9500 \u9472  fern.config.json\
  \uc0\u9500 \u9472  generators.yml\
  \uc0\u9492 \u9472  definition/\
    \uc0\u9500 \u9472  api.yml\
    \uc0\u9492 \u9472  imdb.yml\
```\
\
If you want to initialize Fern with an OpenAPI Specification, run `fern init --openapi path/to/openapi` instead.\
\
```yaml\
fern/\
  \uc0\u9500 \u9472  fern.config.json\
  \uc0\u9500 \u9472  generators.yml # required on Fern version 0.41.0 and above\
  \uc0\u9492 \u9472  openapi/\
    \uc0\u9500 \u9472  openapi.yml\
```\
\
### `fern.config.json`\
\
Every fern folder has a single `fern.config.json` file. This file stores the organization and\
the version of the Fern CLI that you are using.\
\
```json\
\{\
    "organization": "imdb",\
    "version": "0.31.2"\
\}\
```\
\
Every time you run a fern CLI command, the CLI downloads itself at the correct version to ensure\
determinism.\
\
<Note>\
  To upgrade the CLI, run \
\
  `fern upgrade`\
\
  . This will update the version field in \
\
  `fern.config.json`\
\
   \
</Note>\
\
### `generators.yml`\
\
The `generators.yml` file can include information about where your API specification is located, along with which generators you are using, where each package gets published, as well as configuration specific to each generator.\
\
<AccordionGroup>\
  <Accordion title="generators.yml for Python + TypeScript SDKs">\
    ```yaml\
    api: \
      path: ./path/to/openapi.yml\
    groups:\
      public:\
        generators:\
          - name: fernapi/fern-python-sdk\
            version: 3.0.0\
            output:\
              location: pypi\
              package-name: imdb\
              token: $\{PYPI_TOKEN\}\
            github:\
              repository: imdb/imdb-python\
            config:\
              client_class_name: imdb\
          - name: fernapi/fern-typescript-node-sdk\
            version: 0.31.0\
            output:\
              location: npm\
              package-name: imdb\
              token: $\{NPM_TOKEN\}\
            github:\
              repository: imdb/imdb-node\
            config:\
              namespaceExport: imdb\
    ```\
  </Accordion>\
\
  <Accordion title="generators.yml for locating an API definition">\
    ```yaml\
    api: \
      path: ./path/to/openapi.yml\
    ```\
  </Accordion>\
</AccordionGroup>\
\
## Multiple APIs\
\
The Fern folder is capable of housing multiple API definitions. Instead of placing your API definition at the top-level, you can nest them within an `apis` folder. Be sure to include a `generators.yml` file within each API folder that specifies the location of the API definition.\
\
<Tabs>\
  <Tab title="OpenAPI Definition">\
    ```bash\
    fern/\
      \uc0\u9500 \u9472  fern.config.json\
      \uc0\u9500 \u9472  generators.yml\
      \uc0\u9492 \u9472  apis/\
        \uc0\u9492 \u9472  imdb/\
            \uc0\u9500 \u9472  generators.yml\
            \uc0\u9492 \u9472  openapi/\
              \uc0\u9500 \u9472  openapi.yml\
        \uc0\u9492 \u9472  disney/\
            \uc0\u9500 \u9472  generators.yml\
            \uc0\u9492 \u9472  openapi/\
              \uc0\u9500 \u9472  openapi.yml\
    ```\
  </Tab>\
\
  <Tab title="Fern Definition">\
    ```bash\
    fern/\
      \uc0\u9500 \u9472  fern.config.json\
      \uc0\u9500 \u9472  generators.yml\
      \uc0\u9492 \u9472  apis/\
        \uc0\u9492 \u9472  imdb/\
            \uc0\u9500 \u9472  generators.yml\
            \uc0\u9492 \u9472  definition/\
              \uc0\u9500 \u9472  api.yml\
              \uc0\u9492 \u9472  imdb.yml\
        \uc0\u9492 \u9472  disney/\
            \uc0\u9500 \u9472  generators.yml\
            \uc0\u9492 \u9472  definition/\
              \uc0\u9500 \u9472  api.yml\
              \uc0\u9492 \u9472  disney.yml\
    ```\
  </Tab>\
</Tabs>\
\
\
# What is an OpenAPI Specification?\
\
> OpenAPI is a standard for documenting REST APIs\
\
The OpenAPI Specification (OAS) is a framework used by developers to document REST APIs. The specification\
written in JSON or YAML and contains all of your endpoints, parameters, schemas, and authentication schemes.\
Fern is compatible with the latest OAS release, which is currently [v3.1.1](https://spec.openapis.org/#openapi-specification).\
\
<Info>\
   Considering options to generate an OpenAPI spec? Get live support \
\
  [here](https://fern-community.slack.com/join/shared_invite/zt-2dpftfmif-MuAegl8AfP_PK8s2tx350Q%EF%BB%BF#/shared-invite/email)\
\
   \
</Info>\
\
Below is an example of an OpenAPI file:\
\
```yaml openapi.yml \
openapi: 3.0.2\
info:\
  title: Petstore - OpenAPI 3.0\
  description: |-\
    This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\
paths:\
  "/pet":\
    put:\
      tags:\
      - pet\
      summary: Update an existing pet\
      description: Update an existing pet by Id\
      operationId: updatePet\
      requestBody:\
        description: Update an existent pet in the store\
        content:\
          application/json:\
            schema:\
              "$ref": "#/components/schemas/Pet"\
        required: true\
      responses:\
        '200':\
          description: Successful operation\
          content:\
            application/json:\
              schema:\
                "$ref": "#/components/schemas/Pet"\
        '400':\
          description: Invalid ID supplied\
        '404':\
          description: Pet not found\
        '405':\
          description: Validation exception\
      security:\
      - api_key\
components:\
  schemas:\
    Category:\
      type: object\
      properties:\
        id:\
          type: integer\
          format: int64\
          example: 1\
        name:\
          type: string\
          example: Dogs\
    Tag:\
      type: object\
      properties:\
        id:\
          type: integer\
          format: int64\
        name:\
          type: string\
    Pet:\
      required:\
      - name\
      - photoUrls\
      type: object\
      properties:\
        id:\
          type: integer\
          format: int64\
          example: 10\
        name:\
          type: string\
          example: doggie\
        category:\
          "$ref": "#/components/schemas/Category"\
        photoUrls:\
          type: array\
          items:\
            type: string\
        tags:\
          type: array\
          items:\
            "$ref": "#/components/schemas/Tag"\
        status:\
          type: string\
          description: pet status in the store\
          enum:\
          - available\
          - pending\
          - sold\
  securitySchemes:\
    api_key:\
      type: apiKey\
      name: api_key\
      in: header\
```\
\
## Setup your Fern folder\
\
Start by initializing your Fern folder with an OpenAPI spec\
\
<CodeGroup>\
  ```sh file\
  fern init --openapi ./path/to/openapi\
  ```\
\
  ```sh url\
  fern init --openapi https://host/path/to/openapi\
  ```\
</CodeGroup>\
\
This will initialize a directory like the following\
\
```\
fern/\
  \uc0\u9500 \u9472  fern.config.json\
  \uc0\u9500 \u9472  generators.yml\
  \uc0\u9492 \u9472  openapi/\
    \uc0\u9500 \u9472  openapi.yml\
```\
\
\
# Authentication\
\
> Model auth schemes such as bearer, basic, and api key.\
\
Configuring authentication schemes happens in the `components.securitySchemes` section of OpenAPI.\
\
```yml title="openapi.yml" \{2-3\}\
components: \
  securitySchemes: \
    ...\
```\
\
<Note>\
  To apply a security scheme across all endpoints, reference the `securityScheme` within the `security` section of your OpenAPI Specification.\
\
  ```yml title="openapi.yml" \{3, 5-6\}\
  components: \
    securitySchemes: \
      AuthScheme:\
        ...\
  security: \
    - AuthScheme: []\
  ```\
</Note>\
\
## Bearer security scheme\
\
Start by defining a `bearer` security scheme in your `openapi.yml`:\
\
```yml title="openapi.yml" \{3-5\}\
components:\
  securitySchemes:\
    BearerAuth:\
      type: http\
      scheme: bearer\
```\
\
This will generate an SDK where the user would have to provide\
a mandatory argument called `token`.\
\
```ts index.ts\
const client = new Client(\{\
  token: "ey34..."\
\})\
```\
\
If you want to control variable naming and the environment variable to scan,\
use the configuration below:\
\
```yaml title="openapi.yml" \{6-8\}\
components:\
  securitySchemes:\
    BearerAuth:\
      type: http\
      scheme: bearer\
      x-fern-bearer: \
        name: apiKey\
        env: PLANTSTORE_API_KEY\
```\
\
The generated SDK would look like:\
\
```ts index.ts\
\
// Uses process.env.PLANTSTORE_API_KEY\
let client = new Client(); \
\
// token has been renamed to apiKey\
client = new Client(\{\
  apiKey: "ey34..."\
\})\
```\
\
## Basic security scheme\
\
Start by defining a `basic` security scheme in your `openapi.yml`:\
\
```yaml title="openapi.yml" \{3-5\}\
components:\
  securitySchemes:\
    BasicAuth:\
      type: http\
      scheme: basic\
```\
\
This will generate an SDK where the user would have to provide\
a mandatory arguments called `username` and `password`.\
\
```ts index.ts\
const client = new Client(\{\
  username: "joeschmoe"\
  password: "ey34..."\
\})\
```\
\
If you want to control variable naming and environment variables to scan,\
use the configuration below:\
\
```yaml title="openapi.yml" \{6-12\}\
components:\
  securitySchemes:\
    BasicAuth:\
      type: http\
      scheme: basic\
      x-fern-basic:\
        username:\
          name: clientId\
          env: PLANTSTORE_CLIENT_ID\
        password:\
          name: clientSecret\
          env: PLANTSTORE_CLIENT_SECRET\
```\
\
The generated SDK would look like:\
\
```ts index.ts\
\
// Uses process.env.PLANTSTORE_CLIENT_ID and process.env.PLANTSTORE_CLIENT_SECRET\
let client = new Client(); \
\
// parameters have been renamed\
client = new Client(\{\
  clientId: "joeschmoe", \
  clientSecret: "ey34..."\
\})\
```\
\
## ApiKey security scheme\
\
Start by defining an `apiKey` security scheme in your `openapi.yml`:\
\
```yml title="openapi.yml" \{3-5\}\
components: \
  securitySchemes: \
    ApiKey: \
      type: apiKey\
      in: header\
      name: X_API_KEY\
```\
\
This will generate an SDK where the user would have to provide\
a mandatory argument called `apiKey`.\
\
```ts index.ts\
const client = new Client(\{\
  apiKey: "ey34..."\
\})\
```\
\
If you want to control variable naming and environment variables to scan,\
use the configuration below:\
\
```yaml title="openapi.yml" \{7-10\}\
components: \
  securitySchemes: \
    ApiKey: \
      type: apiKey\
      in: header\
      name: X_API_KEY\
      x-fern-header:\
        name: apiToken\
        env: PLANTSTORE_API_KEY\
        prefix: "Token " # Optional      \
```\
\
The generated SDK would look like:\
\
```ts index.ts\
\
// Uses process.env.PLANTSTORE_API_KEY\
let client = new Client(); \
\
// parameters have been renamed\
client = new Client(\{\
  apiToken: "ey34..."\
\})\
```\
\
## Multiple security schemes\
\
If you would like to define multiple security schemes, simply\
list them under `components.securitySchemes`. For example, if you wanted to support\
`basic` and `apiKey` security schemes, see the example below:\
\
```yaml title="openapi.yml" \{3,6\}\
components: \
  securitySchemes: \
    BearerAuth:\
      type: http\
      scheme: bearer  \
    ApiKey: \
      type: apiKey\
      in: header\
      name: X_API_KEY   \
```\
\
\
# HTTP JSON Endpoints\
\
> Document HTTP JSON APIs with the `application/json` content type\
\
Endpoints in OpenAPI are defined underneath the `paths` key. Below is an example of defining\
a single endpoint:\
\
```yml title="openapi.yml" maxLines=0 \{2-18\}\
paths:\
  /pets:\
    post:\
      summary: Create a new pet\
      description: Creates a new pet with the provided information\
      requestBody:\
        required: true\
        content:\
          application/json:\
            schema:\
              $ref: '#/components/schemas/Pet'\
      responses:\
        '200':\
          description: User created successfully\
          content:\
            application/json:\
              schema:\
                $ref: '#/components/schemas/Pet'\
```\
\
## Examples\
\
You can provide examples of requests and responses by using the `examples` key.\
\
```yaml title="openapi.yml" \{12-17,25-30\}\
paths:\
  /pets:\
    post:\
      summary: Create a new pet\
      description: Creates a new pet with the provided information\
      requestBody:\
        required: true\
        content:\
          application/json:\
            schema:\
              $ref: '#/components/schemas/Pet'\
            examples:\
              PetExample:\
                summary: This is an example of a Pet\
                value: \
                  name: Markley\
                  id: 44\
      responses:\
        '200':\
          description: A Pet object\
          content:\
            application/json:\
              schema:\
                $ref: '#/components/schemas/Pet'\
              examples:\
                PetExample:\
                  summary: This is an example of a Pet\
                  value: \
                    name: Markley\
                    id: 44\
```\
\
\
# Multipart File Upload\
\
> Document endpoints with the `multipart/form-data` content type\
\
Multipart requests combine one or more sets of data into a single body, separated by boundaries.\
You typically use these requests for file uploads and for transferring data of several types in a single request\
(for example, a file along with a JSON object).\
\
```yml title="openapi.yml" maxLines=0 \{12-24\}\
paths:\
  /upload:\
    post:\
      summary: Upload a file\
      description: Upload a file using multipart/form-data encoding\
      operationId: uploadFile\
      tags:\
        - file\
      requestBody:\
        required: true\
        content:\
          multipart/form-data:\
            schema:\
              type: object\
              properties:\
                file:\
                  type: string\
                  format: binary\
                  description: The file to upload\
                description:\
                  type: string\
                  description: A description of the file (optional)\
              required:\
                - file\
      responses:\
        "200":\
          description: Successful upload\
          content:\
            application/json:\
              schema:\
                type: object\
                properties:\
                  message:\
                    type: string\
                  fileId:\
                    type: string\
```\
\
Any request body that is defined with a `multipart/form-data` content type, will be\
treated as a multipart request. Within a given multipart request, a string parameter with\
`format:binary` will represent an arbitrary file.\
\
## Array of Files\
\
If your endpoint supports an array of files, then your request body must use\
an array type.\
\
```yml openapi.yml \{12-17\}\
paths:\
  /upload:\
    post:\
      summary: Upload multiple files\
      operationId: uploadFiles\
      requestBody:\
        content:\
          multipart/form-data:\
            schema:\
              type: object\
              properties:\
                files:\
                  type: array\
                  items:\
                    type: string\
                    format: binary\
                  description: An array of files to upload\
```\
\
\
# Server Sent Events and Streaming APIs\
\
> Use the `x-fern-streaming` extension to model streaming endpoints\
\
<Note>\
  The `x-fern-streaming` extension allows you to represent endpoints that are streaming.\
</Note>\
\
## JSON streaming\
\
If your API returns a series of `JSON` chunks as seen below\
\
```json\
\{ "text": "Hi, I am a" \}\
\{ "text": "chatbot. Do you have any"\}\
\{ "text": "questions for me"\}\
```\
\
then simply add the `x-fern-streaming: true` to your OpenAPI operation.\
\
```yaml title="openapi.yml" \{4\}\
paths:\
  /logs:\
    post:\
      x-fern-streaming: true\
      responses:\
        "200":\
          content:\
            application/json:\
              schema:\
                $ref: "#/components/schemas/Chat"\
components:\
  schemas:\
    Chat:\
      type: object\
      properties:\
        text:\
          type: string\
```\
\
## Server sent events\
\
If your API returns server-sent-events, with the `data` and `event` keys as seen below\
\
```json\
data: \{ "text": "Hi, I am a" \}\
data: \{ "text": "chatbot. Do you have any"\}\
data: \{ "text": "questions for me"\}\
```\
\
then make sure to include `format: sse`.\
\
```yaml title="openapi.yml" \{4-5\}\
paths:\
  /logs:\
    post:\
      x-fern-streaming: \
        format: sse\
      responses:\
        "200":\
          content:\
            application/json:\
              schema:\
                $ref: "#/components/schemas/Chat"\
components:\
  schemas:\
    Chat:\
      type: object\
      properties:\
        text:\
          type: string\
```\
\
## `Stream` parameter\
\
It has become common practice for endpoints to have a `stream` parameter that\
controls whether the response is streamed or not. Fern supports this pattern in a first\
class way.\
\
Simply specify the `stream-condition` as well as the ordinary response and the streaming response:\
\
```yaml title="openapi.yml" \{4-10\}\
paths:\
  /logs:\
    post:\
      x-fern-streaming: \
        format: sse\
        stream-condition: $request.stream\
        response: \
          $ref: '#/components/schemas/Chat'\
        response-stream: \
          $ref: '#/components/schemas/ChatChunk'\
components:\
  schemas:\
    Chat:\
      type: object\
      properties:\
        text:\
          type: string\
        tokens: \
          type: number\
    ChatChunk: \
      type: object\
      properties: \
        text: \
          type: string\
```\
\
\
# Define Webhooks in OpenAPI\
\
> Use the `x-fern-webhook` extension to define webhooks in your OpenAPI spec\
\
Simply define a path in your OpenAPI, and add the extension `x-fern-webhook`. Fern will\
treat the `requestBody` as the webhook payload.\
\
```yaml openapi.yml\
paths: \
  /payment/updated/: \
    post: \
      summary: Payment Initiated\
      operationId: initiatePayment\
      x-fern-webhook: true\
      requestBody:\
        content:\
          application/json:\
            schema:\
              type: object\
              properties:\
                amount:\
                  type: number\
                currency:\
                  $ref: '#/components/schemas/Currency'\
              required:\
                - amount\
                - currency \
```\
\
<Info>\
  The path that you choose when defining a webhook can be arbitrary. Since webhooks\
  can be sent to any server, Fern just ignores the path.\
</Info>\
\
\
# Use audiences to filter your API\
\
> Use `x-fern-audiences` to filter to relevant endpoints, schemas and properties\
\
Audiences are a useful tool for segmenting your API for different consumers. Common examples of audiences include `public`\
and `beta`.\
\
<Info>\
  Remember to filter your SDKs and Docs after specifying audiences. If **no audiences** are specified,\
  nothing will be filtered.\
\
  <AccordionGroup>\
    <Accordion title="SDKs">\
      The following example configures the SDK to filter to the `public` audience:\
\
      ```yaml title="generators.yml" \{3-4\}\
      groups:\
        sdks:\
          audiences:\
            - public\
          generators:\
            - name: fernapi/fern-tyepscript-node-sdk\
              version: 0.8.8\
      ```\
    </Accordion>\
\
    <Accordion title="Docs">\
      The following example configures the docs to filter to the `public` audience:\
\
      ```yaml title="docs.yml" \{3-4\}\
      navigation:\
        - api: API Reference\
          audiences:\
            - public\
      ```\
    </Accordion>\
  </AccordionGroup>\
</Info>\
\
## Audiences for servers\
\
To mark a server with a particular audience, add the `x-fern-server-name` and `x-fern-audiences` extension to the relevant server.\
\
In the example below, the `Production` server is only available to public consumers:\
\
```yaml title="openapi.yml" \{3-5\}\
servers:\
  - url: https://api.com\
    x-fern-server-name: Production\
    x-fern-audiences:\
      - public\
```\
\
## Audiences for endpoints\
\
To mark an endpoint with a particular audience, add the `x-fern-audiences` extension to the relevant endpoint.\
\
In the example below, the `POST /users/sendEmail` endpoint is only available to public consumers:\
\
```yaml title="openapi.yml" \{4-5\}\
paths:\
  /users/sendEmail:\
    post:\
      x-fern-audiences:\
        - public\
      operationId: send_email\
```\
\
## Audiences for schemas\
\
Schemas can be marked for different audiences, as well.\
\
In this example, the `Email` type is available to both public and beta customers.\
\
```yaml title="openapi.yml" \{13-15\}\
components:\
  schemas:\
    Email:\
      title: Email\
      type: object\
      properties:\
        subject:\
          type: string\
        body:\
          type: string\
        to:\
          type: string\
      x-fern-audiences:\
        - public\
        - beta\
```\
\
## Audiences for properties\
\
Properties can be marked for different audiences, as well.\
\
In this example, the `to` property is available to beta customers only.\
\
```yaml title="openapi.yml" \{13-17\}\
components:\
  schemas:\
    Email:\
      title: Email\
      type: object\
      properties:\
        subject:\
          type: string\
        body:\
          type: string\
        to:\
          type: string\
          x-fern-audiences:\
            - beta\
```\
\
\
# Customize SDK Method Names\
\
> Use `x-fern-sdk-method-name` and `x-fern-sdk-group-name` to finetune SDK naming.\
\
<Note>\
  The `x-fern-sdk-group-name` and `x-fern-sdk-method-name` extensions allow you to customize the generated SDK method\
  names.\
</Note>\
\
## Usage\
\
In the example below, Fern will generate a method called `client.users.create()` for the `POST /users` endpoint.\
\
```yaml title="openapi.yaml"\
paths:\
  /users:\
    post:\
      x-fern-sdk-group-name: users\
      x-fern-sdk-method-name: create\
```\
\
## Top level methods\
\
If you omit the `x-fern-sdk-group-name` extension, then the generated SDK method will live at the root.\
In the example below, Fern will generate a method called `client.send()`:\
\
```yaml title="openapi.yaml"\
paths:\
  /send:\
    post:\
      x-fern-sdk-method-name: send\
```\
\
## Multiple levels of nesting\
\
If you add more than one `x-fern-sdk-group-name` extension, then the generated SDK will nest group names.\
The order of the group names is preserved in the generated SDK method.\
\
In the example below, Fern will generate a method called `client.users.notifications.send()`:\
\
```yaml title="openapi.yaml"\
paths:\
  /users/notifications:\
    post:\
      x-fern-sdk-group-name:\
        - users\
        - notifications\
      x-fern-sdk-method-name: send\
```\
\
\
# Customize parameter names\
\
> Use `x-fern-parameter-name` to customize query parameter, header and path parameter naming.\
\
<Note>\
  The `x-fern-parameter-name` extension allows you to customize the variable names of parameters in your generated SDKs.\
</Note>\
\
## Headers\
\
In the example below, the header `X-API-Version` is renamed to `version` in the\
generated SDK. The rename makes the SDK more human readable.\
\
```yaml \{8\}\
paths:\
  "/user":\
    get:\
      operationId: list_user\
      parameters:\
        - in: header\
          name: X-API-Version\
          x-fern-parameter-name: version\
          schema:\
            type: string\
          required: true\
```\
\
## Query parameters\
\
In the example below, the query parameter `q` is renamed to `search_terms` in the\
generated SDK. The rename makes the parameter more approachable for end users.\
\
```yaml \{8\}\
paths:\
  "/user/search":\
    get:\
      operationId: search_user\
      parameters:\
        - in: query\
          name: q\
          x-fern-parameter-name: search_terms\
          schema:\
            type: string\
          required: false\
```\
\
## Path parameters\
\
In the example below, the path parameter `userId` is renamed to `id` in the\
generated SDK. The rename makes the SDK less verbose.\
\
```yaml \{8\}\
paths:\
  "/user/\{userId\}":\
    get:\
      operationId: get_user\
      parameters:\
        - in: path\
          name: userId\
          x-fern-parameter-name: id\
          schema:\
            type: string\
          required: false\
```\
\
\
# Other extensions\
\
> Learn about Fern's OpenAPI extensions for authentication overrides, global headers, enum descriptions and names, audiences, and more.\
\
Fern supports different OpenAPI extensions so that you can generate higher-quality SDKs.\
\
## API version\
\
You can define your API version scheme, such as a `X-API-Version` header. The supported versions and default value are specified like so:\
\
```yaml title="openapi.yaml"\
x-fern-version:\
  version:\
    header: X-API-Version\
    default: "2.0.0"\
    values:\
      - "1.0.0"\
      - "2.0.0"\
      - "latest"\
paths: ...\
```\
\
## Global headers\
\
At times, your API will leverage certain headers for every endpoint, or the majority of them, we call these "global headers". For convenience, generated Fern SDKs expose "global headers" to easily be updated on API calls. Take for example an API key, if we declare the API key as a global header, a user will be able to plug theirs in easily:\
\
```python\
import os\
\
class Client:\
\
  def __init__(self, *, apiKey: str):\
```\
\
To configure global headers, Fern will automatically pull out headers that are used in every request, or the majority of requests, and mark them as global.\
In order to label additional headers as global, or to alias the names of global headers, you can leverage the `x-fern-global-headers` extension:\
\
```yaml title="openapi.yml"\
x-fern-global-headers:\
  - header: custom_api_key\
    name: api_key\
  - header: userpool_id\
    optional: true\
```\
\
yields the following client:\
\
```python\
import os\
\
class Client:\
\
  def __init__(self, *, apiKey: str, userpoolId: typing.Optional[str])\
```\
\
## Enum descriptions and names\
\
OpenAPI doesn't natively support adding descriptions to enum values. To do this in Fern you can use the `x-fern-enum`\
extension.\
\
In the example below, we've added some descriptions to enum values. These descriptions will\
propagate into the generated SDK and docs website.\
\
```yaml title="openapi.yml" \{9-13\}\
components:\
  schemas:\
    CardSuit:\
      enum:\
        - clubs\
        - diamonds\
        - hearts\
        - spades\
      x-fern-enum:\
        clubs:\
          description: Some docs about clubs\
        spades:\
          description: Some docs about spades\
```\
\
`x-fern-enum` also supports a `name` field that allows you to customize the name of the enum in code.\
This is particularly useful when you have enums that rely on symbolic characters that would otherwise cause\
generated code not to compile.\
\
For example, the following OpenAPI\
\
```yaml title="openapi.yml" \{9,12\}\
components:\
  schemas:\
    Operand:\
      enum:\
        - '>'\
        - '<'\
      x-fern-enum:\
        '>':\
          name: GreaterThan\
          description: Checks if value is greater than\
        '<':\
          name: LessThan\
          description: Checks if value is less than\
```\
\
would generate\
\
```typescript title="operand.ts"\
export enum Operand \{\
  GreaterThan = ">",\
  LessThan = "<"\
\}\
```\
\
## Schema names\
\
OpenAPI allows you to define inlined schemas that do not have names.\
\
```yaml title="Inline type in openapi.yml" \{11\}\
components:\
  schemas:\
    Movie:\
      type: object\
      properties:\
        name:\
          type: string\
        cast:\
          type: array\
          items:\
            type: object\
            properties:\
              firstName:\
                type: string\
              lastName:\
                type: string\
              age:\
                type: integer\
```\
\
Fern automatically generates names for all the inlined schemas. For example, in this example,\
Fern would generate the name `CastItem` for the inlined array item schema.\
\
```typescript title="Auto-generated name" \{6\}\
export interface Movie \{\
  name?: string;\
  cast?: CastItem[];\
\}\
\
export interface CastItem \{\
  firstName?: string;\
  lastName?: string;\
  age?: integer;\
\}\
```\
\
If you want to override the generated name, you can use the extension `x-fern-type-name`.\
\
```yaml title="openapi.yml" \{12\}\
components:\
  schemas:\
    Movie:\
      type: object\
      properties:\
        name:\
          type: string\
        cast:\
          type: array\
          items:\
            type: object\
            x-fern-type-name: Person\
            properties:\
              firstName:\
                type: string\
              lastName:\
                type: string\
              age:\
                type: integer\
```\
\
This would replace `CastItem` with `Person` and the generated code would read more idiomatically:\
\
```typescript title="Overridden name" \{6\}\
export interface Movie \{\
  name?: string;\
  cast?: Person[];\
\}\
\
export interface Person \{\
  firstName?: string;\
  lastName?: string;\
  age?: integer;\
\}\
```\
\
## Property names\
\
The `x-fern-property-name` extension allows you to customize the variable name for object\
properties.\
\
For example, if you had a property called `_metadata` in your schema but you wanted the\
variable to be called `data` in your SDK you would do the following:\
\
```yaml \{6\}\
components:\
  schemas:\
    MyUser:\
      _metadata:\
        type: object\
        x-fern-property-name: data\
```\
\
## Server names\
\
The `x-fern-server-name` extension is used to name your servers.\
\
```yaml title="openapi.yml"\
servers:\
  - url: https://api.example.com\
    x-fern-server-name: Production\
  - url: https://sandbox.example.com\
    x-fern-server-name: Sandbox\
```\
\
In a generated TypeScript SDK, you'd see:\
\
```typescript title="environment.ts"\
export const ExampleEnvironment = \{\
  Production: "https://api.example.com"\
\} as const;\
\
export type ExampleEnvironment = typeof ExampleEnvironment.Production;\
```\
\
## Base path\
\
The `x-fern-base-path` extension is used to configure the base path prepended to every endpoint.\
\
In the example below, we have configured the `/v1` base path so the full endpoint path is\
`https://api.example.com/v1/users`.\
\
```yaml title="Set the base path in openapi.yml" \{1\}\
x-fern-base-path: /v1\
servers:\
  - url: https://api.example.com\
paths:\
  /users: ...\
```\
\
## Ignoring schemas or endpoints\
\
If you want Fern to skip reading any endpoints or schemas, use the `x-fern-ignore` extension.\
\
To skip an endpoint, add `x-fern-ignore: true` at the operation level.\
\
```yaml title="x-fern-ignore at operation level in openapi.yml" \{4\}\
paths:\
  /users:\
    get:\
      x-fern-ignore: true\
      ...\
```\
\
To skip a schema, add `x-fern-ignore: true` at the schema level.\
\
```yaml title="x-fern-ignore at schema level in openapi.yml" \{4\}\
components:\
  schemas:\
    SchemaToSkip:\
      x-fern-ignore: true\
      ...\
```\
\
## Overlaying extensions\
\
Because of the number of tools that use OpenAPI, it may be more convenient to\
"overlay" your fern specific OpenAPI extensions onto your original definition. \\\
In order to do this you can specify your overrides file in `generators.yml`.\
\
Below is an example of how someone can overlay the extensions `x-fern-sdk-method-name` and\
`x-fern-sdk-group-name` without polluting their original OpenAPI. The combined result is\
shown in the third tab.\
\
<CodeBlocks>\
  ```yaml title="generators.yml" \{3\}\
  api:\
    path: ./openapi/openapi.yaml\
    overrides: ./openapi/overrides.yaml\
  default-group: sdk\
  groups:\
    sdk:\
      generators:\
        - name: fernapi/fern-python-sdk\
          version: 2.2.0\
  ```\
\
  ```yaml title="overrides.yml"\
  paths:\
    /users:\
      get:\
        x-fern-sdk-group-name: users\
        x-fern-sdk-method-name: get\
  ```\
\
  ```yaml title="Overlayed OpenAPI" \{4-5\}\
  paths:\
    /users:\
      get:\
        x-fern-sdk-group-name: users\
        x-fern-sdk-method-name: get\
        summary: Get a list of users\
        description: Retrieve a list of users from the system.\
        responses:\
          '200':\
            description: Successful response\
          '500':\
            description: Internal Server Error\
  ```\
</CodeBlocks>\
\
## Embedding extensions\
\
If instead of overlaying your extensions within an overrides file, as mentioned above. Certain frameworks that generate OpenAPI Specifications make it easy to embed extensions directly from code.\
\
### FastAPI\
\
Please view our page on [FastAPI](/learn/api-definition/openapi/frameworks/fastapi) for more information on how to extend your OpenAPI Specification within FastAPI.\
\
## Request + response examples\
\
While OpenAPI has several fields for examples, there is no easy way\
to associate a request with a response. This is especially useful when\
you want to show more than one example in your documentation.\
\
`x-fern-examples` is an array of examples. Each element of the array\
can contain `path-parameters`, `query-parameters`, `request` and `response`\
examples values that are all associated.\
\
```yaml title="openapi.yml" \{5-16\}\
paths:\
  /users/\{userId\}:\
    get:\
      x-fern-examples:\
        - path-parameters:\
            userId: user-1234\
          response:\
            body:\
              name: Foo\
              ssn: 1234\
        - path-parameters:\
            userId: user-4567\
          response:\
            body:\
              name: Foo\
              ssn: 4567\
components:\
  schemas:\
    User:\
      type: object\
      properties:\
        name:\
          type: string\
        ssn:\
          type: integer\
```\
\
### Code samples\
\
If you'd like to specify custom code samples for your example, use `code-samples`.\
\
```yaml title="openapi.yml" \{11-16\}\
paths:\
  /users/\{userId\}:\
    get:\
      x-fern-examples:\
        - path-parameters:\
            userId: user-1234\
          response:\
            body:\
              name: Foo\
              ssn: 1234\
          code-samples:\
            - sdk: typescript\
              code: |\
                import \{ UserClient \} from "...";\
\
                client.users.get("user-1234")\
```\
\
If you're on the Fern Starter plan or higher for SDKs you won't have to worry about manually adding code samples! Our generators do that for you.\
\
## Availability\
\
The `x-fern-availability` extension is used to mark the availability of an endpoint. The availability information propagates into the generated Fern Docs website as visual tags.\
\
The options are:\
\
* `beta`\
* `generally-available`\
* `deprecated`\
\
The example below marks that the `POST /pet` endpoint is `deprecated`.\
\
```yaml title="x-fern-availability in openapi.yml" \{4\}\
paths:\
  /pet:\
    post:\
      x-fern-availability: deprecated\
```\
\
This renders as:\
\
<Frame caption="A deprecated endpoint">\
  ![Screenshot of API Reference endpoint with tag showing deprecated](https://fern-image-hosting.s3.amazonaws.com/fern/x-fern-availability-example.png)\
</Frame>\
\
### Request new extensions\
\
If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it.\
\
\
# Overlay customizations on an existing OpenAPI spec\
\
> Can't directly modify your OpenAPI spec? No worries, use an overrides file instead.\
\
If you generate your OpenAPI from server code, you may want to tweak your OpenAPI Spec without having to\
touch the generated file.  Fern supports this via an `overrides` file.\
\
<CodeGroup>\
  ```yml openapi.yml\
  paths: \
   /users: \
     post: \
      description: Create a User\
      operationId: users_post\
      requestBody: \
        content:\
          application/json:\
            schema:\
              $ref: '#/components/schemas/User'\
  ```\
\
  ```yml title="overrides.yml" \{4-5\}\
  paths: \
   /users: \
     post: \
      x-fern-sdk-group-name: users\
      x-fern-sdk-method-name: create\
  ```\
\
  ```yml title="combined" \{4-5\}\
  paths: \
   /users/post: \
    post: \
      x-fern-sdk-group-name: users\
      x-fern-sdk-method-name: create      \
      description: Create a User\
      operationId: users_post\
      requestBody: \
        content:\
          application/json:\
            schema:\
              $ref: '#/components/schemas/User'   \
  ```\
</CodeGroup>\
\
## Configuration\
\
Follow the steps below to configure your OpenAPI overrides:\
\
<Steps>\
  ### Create an `overrides.yml`\
\
  Simply create a yaml file and write down all the overrides you want to add:\
\
  ```yaml overrides.yml \
  paths:\
    /v1/history:\
      get:\
        x-fern-sdk-group-name:\
          - history\
        x-fern-sdk-method-name: get_all    \
  ```\
\
  ### Reference the file in your `generators.yml`\
\
  ```yml generators.yml\
  api: \
    path: ../openapi.yml\
    overrides: ../overrides.yml \
  ```\
\
  <Note>\
     The format of the overrides file is independent from the spec. For example, even if your OpenAPI spec is in JSON format, you can write the overrides in yaml. \
  </Note>\
</Steps>\
\
\
# Automatically Update\
\
> Pull your latest OpenAPI Specification into your Fern Folder automatically.\
\
If you host your OpenAPI Specification at a publically available URL, you can have Fern programmatically fetch the latest spec on a preconfigured cadence. By default, this will be done each Monday and open a new PR on the GitHub repo that contains your Fern Folder. This feature requires installation of the [Fern GitHub App](https://github.com/apps/fern-api).\
\
```yml title="generators.yml"\
api:\
  path: openapi/openapi.json\
  origin: https://example.com/openapi.json\
```\
\
\
# FastAPI Instrumentation\
\
> Learn about best practices for creating rich OpenAPI Specifications when instrumenting FastAPI applications.\
\
[FastAPI](https://fastapi.tiangolo.com/) is a popular Python web framework developed by [tiangolo](https://github.com/tiangolo).\
\
The offering brands itself as\
\
> FastAPI is a modern, fast (high-performance), web framework for building APIs with Python based on standard Python type hints.\
\
FastAPI plays very nicely with Fern because it has the power to output OpenAPI Specifications! Below we'll outline some tips for generating a rich OpenAPI with FastAPI.\
\
## OpenAPI generation\
\
By default, FastAPI will generate an OpenAPI Specification for you based on your routes and your data models! You can access this spec by visiting `/docs` on your FastAPI server.\
\
If you are not seeing any OpenAPI Specification (or the Swagger UI), you may need to review your FastAPI server configuration as the path may have been changed, or completely omitted.\
\
```python \{6-8\}\
from fastapi import FastAPI\
\
...\
\
FastAPI(\
    openapi_url="/openapi.json",  # <-- this is the file and URL needed to access the OpenAPI Specification, `docs_url` and `redoc_url` are convenient wrappers that display the file in a UI!\
    docs_url="/docs",             # <-- this is the URL to access the Swagger UI, which will point to your OpenAPI Specification\
    redoc_url="/redoc"            # <-- this is the URL to access the ReDoc UI, which will point to your OpenAPI Specification\
)\
```\
\
## Specifying servers\
\
Fern will automatically generate clients that point to the servers you configure within your OpenAPI Specification, so it's important to specify the servers that your API will be hosted on.\
\
```python \{5\}\
from fastapi import FastAPI\
\
...\
\
app = FastAPI(servers=[\{"url": "http://prod.test.com", "description": "Production server"\}])\
# This creates the following server object in your OpenAPI Specification:\
# "servers":[\{"url":"http://prod.test.com","description":"Production server"\}],\
```\
\
## OpenAPI extensions\
\
FastAPI allows you to add in extra OpenAPI configuration directly within your route, through the use of the `openapi_extra` parameter.\
Below, we've annotated a "good" route within FastAPI that has it's typings as well as Fern extensions to assist in naming.\
\
```python \{5-9\}\
@router.post(\
    "/your/post/endpoint",\
    response_model=YourResponseModel,            #  <-- with FastAPI, it is important to specify your response model so that it comes through to the OpenAPI Specification\
    summary="Get some response for your req",    #  <-- if you'd like to add a description to your endpoint, you can do so here\
    openapi_extra=\{                              #  <-- finally, you can add in your Fern extensions here, these extensions will produce SDK code that looks something like: `client.endpoints.create(...)` in python\
        "x-fern-sdk-method-name": "create",\
        "x-fern-sdk-group-name": "endpoints",\
        "x-fern-availability": "beta",\
    \},\
)\
async def your_post_endpoint(\
    payload: YourRequestModel,\
) -> YourResponseModel:\
```\
\
## Specifying examples\
\
FastAPI allows you to specify examples for your data models, which Fern will pick up and use within your generated SDKs and documentation automatically.\
\
For more information on leveraging examples within Fern, please refer to the [Fern documentation](/learn/api-definition/openapi/extensions/others#request--response-examples).\
\
For more information on this FastAPI functionality, please refer to the [FastAPI documentation](https://fastapi.tiangolo.com/tutorial/schema-extra-example/).\
\
```python \{7-11\}\
from pydantic import BaseModel\
\
class MyObject(BaseModel):\
    id: str\
\
    class Config:\
        schema_extra = \{\
            "example": \{\
                "id": "a-cool-uuid",\
            \}\
        \}\
```\
\
## Additional customization\
\
FastAPI has a lot of flexibility in how you can customize your OpenAPI Specification. Please refer to the [FastAPI documentation](https://fastapi.tiangolo.com/how-to/extending-openapi/#modify-the-openapi-schema) for more information.\
\
\
# What is a Fern Definition?\
\
> A Fern Definition is a set of YAML files that describe your API.\
\
A Fern Definition is a set of YAML files that are the single source of truth for your API. You check your Fern Definition into your repo,\
inside of which describes your API requests, responses, models, paths, methods, errors, and authentication scheme.\
\
<Note>\
  Want to use OpenAPI instead? No worries, we support that [as well](/learn/api-definition/introduction/what-is-an-api-definition#openapi-swagger)\
</Note>\
\
## Fern Definition structure\
\
To initialize a Fern Definition, simply run:\
\
```sh\
npm install -g fern-api\
fern init\
```\
\
This will create the following folder structure in your project:\
\
```bash\
fern/\
\uc0\u9500 \u9472  fern.config.json # root-level configuration\
\uc0\u9500 \u9472  generators.yml # generators you're using\
\uc0\u9492 \u9472  definition/\
  \uc0\u9500 \u9472  api.yml  # API-level configuration\
  \uc0\u9492 \u9472  imdb.yml # endpoints, types, and errors\
```\
\
## Definition file\
\
Each **Fern Definition** file may define:\
\
* **[Custom types](/learn/api-definition/fern/types)**. Use **custom types** to build your data model.\
* **[Endpoints](/learn/api-definition/fern/endpoints)**. A **service** is a set of related REST endpoints.\
* **[Errors](/learn/api-definition/fern/errors)**. An **error** represents a failed (non-200) response from an endpoint.\
* **[Imports](/learn/api-definition/fern/imports)**. Use **imports** to share types across files.\
\
```yml imdb.yml maxLines=0\
service:\
  auth: false\
  base-path: /movies\
  endpoints:\
    createMovie:\
      docs: Add a movie to the database\
      method: POST\
      path: /create-movie\
      request: CreateMovieRequest\
      response: MovieId\
\
    getMovie:\
      method: GET\
      path: /\{movieId\}\
      path-parameters:\
        movieId: MovieId\
      response: Movie\
      errors:\
        - NotFoundError\
        - UnauthorizedError\
\
types:\
  Movie:\
    properties:\
      title: string\
      rating:\
        type: double\
        docs: The rating scale from one to five stars\
      id:\
        type: MovieId\
        docs: The unique identifier for a movie\
\
  CreateMovieRequest:\
    properties:\
      title: string\
      rating: double\
\
errors:\
  NotFoundError:\
    http:\
      statusCode: 404\
    type:\
      properties:\
        id: MovieId\
\
  UnauthorizedError:\
    http:\
      statusCode: 401\
```\
\
## Why another format?\
\
Google built gRPC. Amazon built Smithy. Facebook built GraphQL. Palantir built\
Conjure. These companies rejected OpenAPI in favor of a more concise API Definition Language.\
\
We built Fern to productize this design and make it accessible to all\
software companies.\
\
<Info>\
  Despite being a different format for describing APIs, **you are never locked in to Fern.** It's easy to convert your\
  [Fern Definition to OpenAPI](/learn/api-definition/fern/export-openapi).\
</Info>\
\
\
# Authentication\
\
> Model auth schemes such as bearer, basic, custom headers, and oauth.\
\
Configuring authentication schemes happens in the `api.yml` file.\
\
```bash \{5\}\
fern/\
\uc0\u9500 \u9472  fern.config.json # root-level configuration\
\uc0\u9500 \u9472  generators.yml # generators you're using\
\uc0\u9492 \u9472  definition/\
  \uc0\u9500 \u9472  api.yml  # API-level configuration\
  \uc0\u9492 \u9472  imdb.yml # endpoints, types, and errors\
```\
\
To add an authentication scheme, specify the authentication method under the `auth-schemes` section.\
\
```yaml api.yml \{1-2\}\
auth-schemes:\
  AuthScheme:                     \
    ...\
```\
\
<Note>\
  To apply an authentication scheme across all endpoints, reference the `auth-scheme` within the `auth` section of your `api.yml` file.\
\
  ```yaml api.yml \{1\}\
  auth: AuthScheme                  \
  auth-schemes:\
    AuthScheme:                     \
      ...\
  ```\
</Note>\
\
## Bearer authentication\
\
Start by defining a `Bearer` authentication scheme in `api.yml`:\
\
```yaml api.yml\
auth: Bearer                  \
auth-schemes:\
  Bearer:                     \
    scheme: bearer\
```\
\
This will generate an SDK where the user would have to provide\
a mandatory argument called `token`.\
\
```ts index.ts\
const client = new Client(\{\
  token: "ey34..."\
\})\
```\
\
If you want to control variable naming and the environment variable to scan,\
use the configuration below:\
\
```yaml title="api.yml" \{5-7\}\
auth: Bearer                  \
auth-schemes:\
  Bearer:                     \
    scheme: bearer\
    token:\
      name: apiKey \
      env: PLANTSTORE_API_KEY\
```\
\
The generated SDK would look like:\
\
```ts index.ts\
\
// Uses process.env.PLANTSTORE_API_KEY\
let client = new Client(); \
\
// token has been renamed to apiKey\
client = new Client(\{\
  apiKey: "ey34..."\
\})\
```\
\
## Basic authentication\
\
Start by defining a `Basic` authentication scheme in `api.yml`:\
\
```yaml api.yml\
auth: Basic                  \
auth-schemes:\
  Basic:                     \
    scheme: basic\
```\
\
This will generate an SDK where the user would have to provide\
a mandatory arguments called `username` and `password`.\
\
```ts index.ts\
const client = new Client(\{\
  username: "joeschmoe"\
  password: "ey34..."\
\})\
```\
\
If you want to control variable naming and environment variables to scan,\
use the configuration below:\
\
```yaml title="api.yml" \{5-11\}\
auth: Basic                  \
auth-schemes:\
  Basic:                     \
    scheme: basic\
    username:\
      name: clientId\
      env: PLANTSTORE_CLIENT_ID\
    password:\
      name: clientSecret\
      env: PLANTSTORE_CLIENT_SECRET\
```\
\
The generated SDK would look like:\
\
```ts index.ts\
\
// Uses process.env.PLANTSTORE_CLIENT_ID and process.env.PLANTSTORE_CLIENT_SECRET\
let client = new Client(); \
\
// parameters have been renamed\
client = new Client(\{\
  clientId: "joeschmoe", \
  clientSecret: "ey34..."\
\})\
```\
\
## Custom header (e.g. API key)\
\
You can also create your own authentication scheme with customized headers.\
\
```yaml title="api.yml" \{3-5\}\
auth: ApiKeyAuthScheme\
auth-schemes:\
  ApiKeyAuthScheme:\
    header: X-API-Key\
    type: string\
```\
\
This will generate an SDK where the user would have to provide\
a mandatory argument called `apiKey`.\
\
```ts index.ts\
const client = new Client(\{\
  xApiKey: "ey34..."\
\})\
```\
\
If you want to control variable naming and environment variables to scan,\
use the configuration below:\
\
```yaml title="api.yml" \{7-8\}\
auth: ApiKeyAuthScheme\
auth-schemes:\
  ApiKeyAuthScheme:\
    header: X-API-Key\
    type: string\
    name: apiKey\
    env: PLANTSTORE_API_KEY\
```\
\
The generated SDK would look like:\
\
```ts index.ts\
\
// Uses process.env.PLANTSTORE_API_KEY\
let client = new Client(); \
\
// parameters have been renamed\
client = new Client(\{\
  apiKey: "ey34..."\
\})\
```\
\
## OAuth client credentials\
\
If your API uses OAuth, you can specify an oauth scheme. Note that you'll need to define a token retrieval endpoint.\
\
```yaml api.yml\
name: api\
\
imports:\
  auth: auth.yml\
\
auth: OAuthScheme\
auth-schemes:\
  OAuthScheme:\
    scheme: oauth\
    type: client-credentials\
    client-id-env: YOUR_CLIENT_ID\
    client-secret-env: YOUR_CLIENT_SECRET\
    get-token:\
      endpoint: auth.getToken               \
      response-properties:\
        access-token: $response.access_token \
        expires-in: $response.expires_in    \
\
```\
\
If the `expires-in` property is set, the generated OAuth token provider will automatically refresh the token when it expires.\
Otherwise, it's assumed that the access token is valid indefinitely.\
\
With this, all of the OAuth logic happens automatically in the generated SDKs. As long as you configure these settings, your\
client will automatically retrieve an access token and refresh it as needed.\
\
When using the docs playground, `token-header` and `token-prefix` can optionally be set to customize the header key name and\
header value prefix, to match the expected format of the API auth scheme.\
\
For example, the following would produce a header `Fern-Authorization: Fern-Bearer <token>`:\
\
```yaml api.yml \{5-6\}\
auth-schemes:\
  OAuthScheme:\
    scheme: oauth\
    type: client-credentials\
    token-header: Fern-Authorization\
    token-prefix: Fern-Bearer\
    get-token:\
      ...   \
```\
\
\
# Types in Fern Definition\
\
> Types describe the data model of your API. Fern has many built-in types and supports custom types, as well as extending and aliasing objects, and unions.\
\
Types describe the data model of your API.\
\
## Built-in types\
\
* `string`\
* `integer`\
* `long`\
* `double`\
* `boolean`\
* `datetime` *An [RFC 3339, section 5.6 datetime](https://ijmacd.github.io/rfc3339-iso8601/). For example, `2017-07-21T17:32:28Z`.*\
* `date` *An RFC 3339, section 5.6 date (YYYY-MM-DD). For example, `2017-07-21`.*\
* `uuid`\
* `base64`\
* `list` *e.g., list\\<string>*\
* `set` *e.g., set\\<string>*\
* `map` *e.g., map\\<string, integer>*\
* `optional` *e.g., optional\\<string>*\
* `literal` *e.g., literal\\<"Plants">*\
* `unknown` *Represents arbitrary JSON.*\
\
## Custom types\
\
Creating your own types is easy in Fern!\
\
### Objects\
\
The most common custom types are **objects**.\
\
In Fern, you use the `"properties"` key to create an object:\
\
```yaml \{3,8\}\
types:\
  Person:\
    properties:\
      name: string\
      address: Address\
\
  Address:\
    properties:\
      line1: string\
      line2: optional<string>\
      city: string\
      state: string\
      zip: string\
      country: literal<"USA">\
```\
\
These represent JSON objects:\
\
```json\
\{\
  "name": "Alice",\
  "address": \{\
    "line1": "123 Happy Lane",\
    "city": "New York",\
    "state": "NY",\
    "zip": "10001",\
    "country": "USA"\
  \}\
\}\
```\
\
You can also use **extends** to compose objects:\
\
```yaml \{6\}\
types:\
  Pet:\
    properties:\
      name: string\
  Dog:\
    extends: Pet\
    properties:\
      breed: string\
```\
\
You can extend multiple objects:\
\
```yaml \{3-5\}\
types:\
  GoldenRetriever:\
    extends:\
      - Dog\
      - Pet\
    properties:\
      isGoodBoy: boolean\
```\
\
### Aliases\
\
An Alias type is a renaming of an existing type. This is usually done for clarity.\
\
```yaml\
types:\
  # UserId is an alias of string\
  UserId: string\
\
  User:\
    properties:\
      id: UserId\
      name: string\
```\
\
### Enums\
\
An enum represents a string with a set of allowed values.\
\
In Fern, you use the `"enum"` key to create an enum:\
\
```yaml \{3\}\
types:\
  WeatherReport:\
    enum:\
      - SUNNY\
      - CLOUDY\
      - RAINING\
      - SNOWING\
```\
\
Enum names are restricted to `A-Z`, `a-z`, `0-9`, and `_` to ensure that generated code can compile across all of the languages that Fern can output. If you have an enum that doesn't follow this convention, you can use the `"name"` key to specify a custom name:\
\
```yaml\
types:\
  Operator:\
    enum:\
      - name: LESS_THAN # <--- the name that will be used in SDKs\
        value: '<' # <--- the value that will be serialized\
      - name: GREATER_THAN\
        value: '>'\
      - name: NOT_EQUAL\
        value: '!='\
```\
\
### Discriminated Unions\
\
Fern supports tagged unions (a.k.a. discriminated unions). Unions are useful for\
polymorphism. This is similar to the `oneOf` concept in OpenAPI.\
\
In Fern, you use the `"union"` key to create an union:\
\
```yaml \{3-5\}\
types:\
  Animal:\
    union:\
      dog: Dog\
      cat: Cat\
  Dog:\
    properties:\
      likesToWoof: boolean\
  Cat:\
    properties:\
      likesToMeow: boolean\
```\
\
In JSON, unions have a **discriminant property** to differentiate between\
different members of the union. By default, Fern uses `"type"` as the\
discriminant property:\
\
```json\
\{\
  "type": "dog",\
  "likesToWoof": true\
\}\
```\
\
You can customize the discriminant property using the "discriminant" key:\
\
```yaml \{3\}\
 types:\
   Animal:\
     discriminant: animalType\
     union:\
       dog: Dog\
       cat: Cat\
   Dog:\
     properties:\
       likesToWoof: boolean\
   Cat:\
     properties:\
       likesToMeow: boolean\
```\
\
This corresponds to a JSON object like this:\
\
```json\
\{\
  "animalType": "dog",\
  "likesToWoof": true\
\}\
```\
\
### Undiscriminated Unions\
\
Undiscriminated unions are similar to discriminated unions, however you don't\
need to define an explicit discriminant property.\
\
```yaml\
MyUnion:\
  discriminated: false\
  union:\
    - string\
    - integer\
```\
\
### Generics\
\
Fern supports shallow generic objects, to minimize code duplication. You can\
define a generic for reuse like so:\
\
```yaml\
MySpecialMapItem<Key, Value>:\
  properties:\
    key: Key, \
    value: Value,\
    diagnostics: string\
```\
\
Now, you can instantiate generic types as a type alias:\
\
```yml\
StringIntegerMapItem:\
  type: Response<string, number>\
\
StringStringMapItem:\
  type: Response<string, string>\
```\
\
You can now freely use this type as if it were any other type! Note, generated\
code will not use generics. The above example will be generated in typescript as:\
\
```typescript\
type StringIntegerMapItem = \{\
  key: string,\
  value: number,\
  diagnostics: string\
\}   \
 \
type StringStringMapItem = \{\
  key: string,\
  value: string,\
  diagnostics: string\
\}\
```\
\
### Documenting types\
\
You can add documentation for types. These docs are passed into the compiler,\
and are incredibly useful in the generated outputs (e.g., docstrings in SDKs).\
\
<CodeBlock title="Fern Definition">\
  ```yaml\
  types:\
    Person:\
      docs: A person represents a human being\
      properties:\
        name: string\
        age:\
          docs: age in years\
          type: integer\
  ```\
</CodeBlock>\
\
<CodeBlock title="Generated TypeScript SDK from Fern Definition">\
  ```typescript\
  /**\
   * A person represents a human being\
   */\
  interface Person \{\
    name: string;\
    // age in years\
    age: number;\
  \}\
  ```\
</CodeBlock>\
\
\
# Endpoints in Fern Definition\
\
> Organize related API endpoints into a service in Fern Definition and define each endpoint's URL, HTTP method, request, response, errors, and more.\
\
In Fern, you organize related endpoints into a **Service**. This grouping\
improves clarity and makes the generated SDKs more idiomatic.\
\
## Service definition\
\
Each service defines:\
\
1. A **base-path**: A common prefix for all the endpoints' HTTP paths\
2. Whether the service requires [authentication](/learn/api-definition/fern/authentication)\
3. **Endpoints**\
\
<CodeBlock title="user.yml">\
  ```yaml\
    service: \
      base-path: /users \
      auth: false \
      endpoints: \{\}\
  ```\
</CodeBlock>\
\
## Endpoints\
\
An endpoint includes:\
\
* A **URL path** *(Optionally including path parameters)*\
* A **Display Name** *(Optional)*\
* An **HTTP Method**\
* **Request information** *(Optional)*\
  * **Query-parameters**\
  * **Headers**\
  * **Request body**\
* **Successful (200) response** information *(Optional)*\
* **Error (non-200) responses** that this endpoint might return *(Optional)*\
\
## URL path\
\
Each endpoint has a URL path.\
\
<CodeBlock title="user.yml">\
  ```yaml \{6\}\
  service:\
    base-path: /users\
    auth: false\
    endpoints:\
      getAllUsers:\
        path: /all\
        method: GET\
  ```\
</CodeBlock>\
\
The full path for the endpoint is the concatenation of:\
\
* The [environment](/learn/api-definition/fern/api-yml/environments) URL\
* The service `base-path`\
* The endpoint `path`\
\
## Display name\
\
The display name will appear as the title of an endpoint. By default, the display name is equal to the 'Title Case' of the endpoint name. If you would like to customize the endpoint name, you can **set the display name**.\
\
In the example below, ["Create User"](https://plantstore.dev/api-reference/user/create-user) displays as the title of the endpoint page within the API Reference.\
\
<CodeBlock title="user.yml">\
  ```yaml \{7\}\
  service:\
    base-path: /\
    auth: false\
    endpoints:\
      createUser:\
        path: /user\
        display-name: Create user\
        method: POST\
  ```\
</CodeBlock>\
\
## Path parameters\
\
Supply path parameters for your endpoints to create dynamic URLs.\
\
<CodeBlock title="user.yml">\
  ```yaml \{6-8\}\
  service:\
    base-path: /users\
    auth: false\
    endpoints:\
      getUser:\
        path: /\{userId\} \
        path-parameters: \
          userId: string\
        method: GET\
  ```\
</CodeBlock>\
\
Services can also have path-parameters:\
\
<CodeBlock title="project.yml">\
  ```yaml \{2-4\}\
  service: \
    base-path: /projects/\{projectId\}\
    path-parameters: \
      projectId: string \
    auth: false \
    endpoints: \
      ...\
  ```\
</CodeBlock>\
\
## Query parameters\
\
Each endpoint can specify query parameters:\
\
<CodeBlock title="user.yml">\
  ```yaml\
  service:\
    base-path: /users\
    auth: false\
    endpoints:\
      getAllUsers:\
        path: /all\
        method: GET\
        request:\
          # this name is required for idiomatic SDKs\
          name: GetAllUsersRequest\
          query-parameters:\
            limit: optional<integer>\
  ```\
</CodeBlock>\
\
### `allow-multiple`\
\
Use `allow-multiple` to specify that a query parameter is allowed\
multiple times in the URL, as in `?filter=jane&filter=smith`. This will alter\
the generated SDKs so that consumers can provide multiple values for the query\
parameter.\
\
<CodeBlock title="user.yml">\
  ```yaml \{5\}\
    ...\
    query-parameters:\
      filter:\
        type: string\
        allow-multiple: true\
  ```\
</CodeBlock>\
\
## Auth\
\
Each endpoint can override the auth behavior specified in the service.\
\
<CodeBlock title="user.yml">\
  ```yaml\
  service: \
    base-path: /users \
    auth: false \
    endpoints: \
      getMe: \
        path: "" \
        method: GET \
        # This endpoint will be authed \
        auth: true \
        docs: Return the current user based on Authorization header. \
  ```\
</CodeBlock>\
\
## Headers\
\
Each endpoint can specify request headers:\
\
<CodeBlock title="user.yml">\
  ```yaml\
  service: \
    base-path: /users \
    auth: false \
    endpoints: \
      getAllUsers: \
        path: /all\
        method: GET \
        request: \
          # this name is required for idiomatic SDKs name:\
          name: GetAllUsersRequest \
          headers: \
            X-Endpoint-Header: string\
  ```\
</CodeBlock>\
\
Services can also specify request headers. These headers will cascade to the service's endpoints.\
\
<CodeBlock title="user.yml">\
  ```yaml \{4-5\} \
  service: \
    base-path: /users \
    auth: false \
    headers: \
      X-Service-Header: string \
    endpoints: \
      getAllUsers: \
        path: /all \
        method: GET \
        request: \
          # this name is required for idiomatic SDKs \
          name: GetAllUsersRequest \
          headers: \
            X-Endpoint-Header: string\
  ```\
</CodeBlock>\
\
## Request body\
\
Endpoints can specify a request body type.\
\
<CodeBlock title="user.yml">\
  ```yaml \{10\}\
  service:\
    base-path: /users\
    auth: false\
    endpoints:\
      setUserName:\
        path: /\{userId\}/set-name\
        path-parameters:\
          userId: string\
        method: POST\
        request: string\
  ```\
</CodeBlock>\
\
### Inlining a request body\
\
If the request body is an object, you can **inline the type declaration**. This\
makes the generated SDKs a bit more idiomatic.\
\
<CodeBlock title="user.yml">\
  ```yaml\
  service: \
    base-path: /users \
    auth: false \
    endpoints: \
      createUser: \
        path: /create \
        method: POST \
        request: \
          # this name is required for idiomatic SDKs \
          name: CreateUserRequest \
          body: \
            properties: \
              userName: string\
  ```\
</CodeBlock>\
\
## Success response\
\
Endpoints can specify a `response`, which is the type of the body that will be\
returned on a successful (200) call.\
\
<CodeBlock title="user.yml">\
  ```yaml\
  service:\
    base-path: /users\
    auth: false\
    endpoints:\
      getAllUsers:\
        path: /all\
        method: GET\
        response: list<User>\
\
  types:\
    User:\
      properties:\
        userId: string\
        name: string\
  ```\
</CodeBlock>\
\
## Response status codes\
\
You can also use the `status-code` field to specify a custom status code\
for a success response.\
\
<CodeBlock title="user.yml">\
  ```yaml \{11\}\
  service:\
    base-path: /users\
    auth: false\
    endpoints:\
      create: :\
        path: ""\
        method: POST\
        request: CreateUserRequest\
        response: \
          type: User\
          status-code: 201\
\
  types:\
    User:\
      properties:\
        userId: string\
        name: string\
  ```\
</CodeBlock>\
\
## Error responses\
\
Endpoints can specify error responses, which detail the non-200 responses that\
the endpoint might return.\
\
<CodeBlock title="user.yml">\
  ```yaml\
  service:\
    base-path: /users\
    auth: false\
    endpoints:\
      getUser:\
        path: /\{userId\}\
        path-parameters:\
          userId: string\
        method: GET\
        response: User\
        errors:\
          - UserNotFoundError\
\
  types:\
    User:\
      properties:\
        userId: string\
        name: string\
\
  errors:\
    UserNotFoundError:\
      status-code: 404\
  ```\
</CodeBlock>\
\
You can learn more about how to define errors on the [Errors](/learn/api-definition/fern/errors) page.\
\
## Specifying examples\
\
When you declare an example, you can also specify some examples of how that\
endpoint might be used. These are used by the compiler to enhance the generated\
outputs. Examples will show up as comments in your SDKs, API documentation, and Postman collection.\
\
You may add examples for endpoints, types, and errors.\
\
<CodeBlock title="user.yml">\
  ```yaml \{13-19\}\
  service:\
    base-path: /users\
    auth: false\
    endpoints:\
      getUser:\
        path: /\{userId\}\
        path-parameters:\
          userId: string\
        method: GET\
        response: User\
        errors:\
          - UserNotFoundError\
        examples:\
          - path-parameters:\
              userId: alice-user-id\
            response:\
              body:\
                userId: alice-user-id\
                name: Alice\
\
  types:\
    User:\
      properties:\
        userId: string\
        name: string\
\
  errors:\
    UserNotFoundError:\
      status-code: 404\
  ```\
</CodeBlock>\
\
If you're adding an example to an endpoint and the type already has an example, you can reference it using `$`.\
\
```yaml\
service:\
  auth: true\
  base-path: /address\
  endpoints:\
    create:\
      method: POST\
      path: ""\
      request: CreateAddress\
      response: Address\
      examples:\
        - request: $CreateAddress.WhiteHouse\
          response:\
            body: $Address.WhiteHouseWithID\
\
  CreateAddress:\
    properties:\
      street1: string\
      street2: optional<string>\
      city: string\
      state: string\
      postalCode: string\
      country: string\
      isResidential: boolean\
    examples:\
      - name: WhiteHouse\
        value:\
          street1: 1600 Pennsylvania Avenue NW\
          city: Washington DC\
          state: Washington DC\
          postalCode: "20500"\
          country: US\
          isResidential: true\
\
  Address:\
    extends: CreateAddress\
    properties:\
      id:\
        type: uuid\
        docs: The unique identifier for the address.\
    examples:\
      - name: WhiteHouseWithID\
        value:\
          id: 65ce514c-41e3-11ee-be56-0242ac120002\
          street1: 1600 Pennsylvania Avenue NW\
          city: Washington DC\
          state: Washington DC\
          postalCode: "20500"\
          country: US\
          isResidential: true\
```\
\
Examples contain all the information about the endpoint call, including\
the request body, path parameters, query parameters, headers, and response body.\
\
<CodeBlock title="user.yml">\
  ```yaml\
  examples: \
    - path-parameters: \
        userId: some-user-id \
      query-parameters:\
        limit: 50 \
      headers: \
        X-My-Header: some-value \
      response: \
        body: \
          response-field: hello\
  ```\
</CodeBlock>\
\
### Failed examples\
\
You can also specify examples of failed endpoints calls. Add the `error`\
property to a response example to designate which failure you're demonstrating.\
\
<CodeBlock title="user.yml">\
  ```yaml \{5\}\
  examples:\
    - path-parameters:\
        userId: missing-user-id\
      response:\
        error: UserNotFoundError\
\
  errors:\
    UserNotFoundError:\
      status-code: 404\
  ```\
</CodeBlock>\
\
If the error has a body, then you must include the body in the example.\
\
<CodeBlock title="user.yml">\
  ```yaml \{6, 11\}\
  examples:\
    - path-parameters:\
        userId: missing-user-id\
      response:\
        error: UserNotFoundError\
        body: "User with id `missing-user-id` was not found"\
\
  errors:\
    UserNotFoundError:\
      status-code: 404\
      type: string\
  ```\
</CodeBlock>\
\
### Referencing examples from types\
\
To avoid duplication, you can reference examples from types using `$`.\
\
<CodeBlock title="user.yml">\
  ```yaml \{12\}\
  service:\
    base-path: /users\
    auth: true\
    endpoints:\
      getUser:\
        method: GET\
        path: /\{userId\}\
        path-parameters:\
          userId: UserId\
        examples:\
          - path-parameters:\
              userId: $UserId.Example1\
\
  types:\
    UserId:\
    type: integer\
    examples: \
      - name: Example1\
        value: user-id-123\
  ```\
</CodeBlock>\
\
\
# HTTP JSON Endpoints\
\
Endpoints in Fern are defined underneath the `endpoints` key. Below is an example of defining\
a single REST endpoint:\
\
```yml title="users.yml" maxLines=0\
service: \
  base-path: /users \
  auth: false \
  endpoints: \
    createUser: \
      path: /create \
      method: POST \
      request: \
        body: \
          properties: \
            userName: string\
```\
\
## Examples\
\
You can provide examples of requests and responses by using the `examples` key.\
\
```yaml \{11-17\}\
service:\
  base-path: /users\
  auth: false\
  endpoints:\
    getUser:\
      path: /\{userId\}\
      path-parameters:\
        userId: string\
      method: GET\
      response: User\
      examples:\
        - path-parameters:\
            userId: alice-user-id\
          response:\
            body:\
              userId: alice-user-id\
              name: Alice\
```\
\
\
# Multipart File Upload\
\
> Document endpoints with the `multiform` content type.\
\
Endpoints in Fern are defined underneath the `endpoints` key. If your endpoint request includes file uploads, you can use the `file` type to indicate the request is of a `multiform` content type. The example below demonstrates an endpoint which includes a file in the request body.\
\
<CodeBlock title="document.yml">\
  ```yaml \{12\}\
  service:\
    base-path: /documents\
    auth: false\
    endpoints:\
      uploadDocument:\
        path: /upload\
        method: POST\
        request:\
          name: UploadDocumentRequest\
          body:\
            properties:\
              file: file\
  ```\
</CodeBlock>\
\
Within a given multipart request, a string parameter with `format:binary` will represent an arbitrary file.\
\
## List of Files\
\
If your endpoint supports a list of files, then your request body must indicate such.\
\
<CodeBlock title="document.yml">\
  ```yaml \{12\}\
  service:\
    base-path: /documents\
    auth: false\
    endpoints:\
      uploadDocuments:\
        path: /upload\
        method: POST\
        request:\
          name: UploadDocumentsRequest\
          body:\
            properties:\
              files: list<file>\
  ```\
</CodeBlock>\
\
\
# Server Sent Events and Streaming APIs\
\
> Use the `response-stream` key to model streaming endpoints\
\
<Note>\
  Specifying `response-stream` on an endpoints allows you to represent endpoint responses that are streaming.\
</Note>\
\
## JSON streaming\
\
If your API returns a series of `JSON` chunks as seen below\
\
```json\
\{ "text": "Hi, I am a" \}\
\{ "text": "chatbot. Do you have any"\}\
\{ "text": "questions for me"\}\
```\
\
then simply specify the response under `response-stream` for your endpoint.\
\
```yaml title="chat.yml" \{4\}\
service:\
  base-path: /chat\
  endpoints:\
    stream:\
      method: POST\
      path: ""\
      response-stream: Chat\
\
types:\
  Chat:\
    properties:\
      text: string\
```\
\
## Server sent events\
\
If your API returns server-sent-events, with the `data` and `event` keys as seen below\
\
```json\
data: \{ "text": "Hi, I am a" \}\
data: \{ "text": "chatbot. Do you have any"\}\
data: \{ "text": "questions for me"\}\
```\
\
then make sure to include `format: sse`.\
\
```yaml title="chat.yml" \{9\}\
service:\
  base-path: /chat\
  endpoints:\
    stream:\
      method: POST\
      path: ""\
      response-stream:\
        type: Chat\
        format: sse\
\
types:\
  Chat:\
    properties:\
      text: string        \
```\
\
## `Stream` parameter\
\
It has become common practice for endpoints to have a `stream` parameter that\
controls whether the response is streamed or not. Fern supports this pattern in a first\
class way.\
\
Simply specify the `stream-condition` as well as the ordinary response and the streaming response:\
\
```yaml title="chat.yml" \{7\}\
service:\
  base-path: /chat\
  endpoints:\
    stream:\
      method: POST\
      path: ""\
      stream-condition: $request.stream\
      request:\
        name: StreamChatRequest\
        body: \
          properties: \
            stream: boolean\
      response: Chat\
      response-stream:\
        type: ChatChunk\
        format: sse\
\
types:\
  Chat:\
    properties:\
      text: string\
      tokens: integer\
  ChatChunk:\
    properties:\
      text: string\
```\
\
\
# Webhooks in the Fern Definition\
\
> Learn how to define webhooks in the Fern Definition\
\
In Fern, you can specify webhooks in your API definition. The webhooks will be included\
in both the generated SDKs and the API documentation.\
\
## Webhook definition\
\
Each webhook defines:\
\
1. **Method**: The HTTP Method that the webhook will use (either `GET` or `POST`)\
2. **Headers**: The headers that the webhook will send\
3. **Payload**: The schema of the webhook payload\
\
<CodeBlock title="webhooks.yml">\
  ```yaml \{2-10\}\
  webhooks: \
    paymentNotification: \
      display-name: Payment Notification\
      docs: Receive a notification when a payment changes status\
      method: POST \
      headers: \
        X-Signature-Primary: \
          type: string \
          docs: An HMAC signature of the payload\
      payload: PaymentNotificationPayload\
\
  types: \
    PaymentNotificationPayload: \
      discriminant: notificationType\
      union: \
        queued: QueuedPaymentNotification\
        processing: ProcessingPaymentNotification\
        completed: CompletedPaymentNotification\
  ```\
</CodeBlock>\
\
### Inlined payloads\
\
You can inline the schema of the payload by doing the following:\
\
<CodeBlock title="webhooks.yml">\
  ```yaml\
  webhooks: \
    paymentNotification: \
      display-name: Payment Notification\
      docs: Receive a notification when a payment changes status\
      method: POST \
      headers: \
        X-Signature-Primary: \
          type: string \
          docs: An HMAC signature of the payload\
      payload:\
        name: PaymentNotificationPayload\
        properties: \
          id:\
            type: string\
            docs: The notification id\
          amount: double\
          currency: Currency\
  ```\
</CodeBlock>\
\
\
# WebSockets in the Fern Definition\
\
> Learn how to define WebSockets in the Fern Definition\
\
WebSockets enable a user to create a connection with a server, over which bidirectional communication can be sent.\
\
In Fern, you can specify WebSockets in your API definition. The WebSockets will be included in both the generated SDKs and the API documentation.\
\
## WebSocket definition\
\
Each WebSocket is defined in its own file, where it is described by the `channel` object.\
\
### The channel object\
\
A `channel` is defined by the following fields:\
\
* `auth`: The authentication scheme for the WebSocket\
* `path`: The path of the WebSocket\
* `headers` *(Optional)*: Any headers the WebSocket will send\
* `path-parameters` *(Optional)*: Any path parameters in the WebSocket path\
* `query-parameters` *(Optional)*: Any query parameters used in the initial request of the WebSocket\
* `messages` *(Optional)*: The schemas of the messages the WebSocket can send and receive once connected\
  * `origin`: The entity that sent the message (e.g. `client` or `server`)\
  * `body`: The schema of the message\
* `examples`: Example WebSocket connection *(Optional)*\
\
### WebSocket example\
\
<CodeBlock title="chat.yml">\
  ```yaml\
  channel:\
    path: /chat\
    auth: false\
    query-parameters:\
      model_id:\
        type: optional<string>\
        docs: The unique identifier of the model.\
      model_version:\
        type: optional<integer>\
        docs: The version number of the model.\
    messages:\
      publish:\
        origin: client\
        body: PublishEvent\
      subscribe:\
        origin: server\
        body: SubscribeEvent\
    examples: \
      - query-parameters: \
          model_id: "123"\
        messages: \
          - type: publish\
            body:\
              text: "Hello, world."\
          - type: subscribe\
            body: \
              id: "23823049"\
              message: "Hello there, how are you?"\
  types:\
    PublishEvent:\
      docs: The input from the user to send through the WebSocket. \
      properties: \
        text: \
          type: string\
          docs: The user text to send into the conversation. \
    SubscribeEvent:\
      docs: The response from the server sent through the WebSocket.\
      properties: \
        id: \
          type: string\
          docs: The id of the message. \
        message:\
          type: string\
          docs: The message sent through the socket. \
  ```\
</CodeBlock>\
\
## WebSocket API Reference\
\
### WebSocket Reference\
\
Fern renders a unique reference page for WebSockets. The **Handshake** section outlines the protocol for connecting with the server, while the **Send** and **Receive** sections outline the message schemas that can be sent between the client and server.\
\
<Frame caption="Cartesia's WebSocket Reference page">\
  <img src="file:acb0b7f0-4bbc-47a0-996a-a0d59551604d" alt="The WebSocket Reference" />\
</Frame>\
\
### WebSocket Playground\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
Users can connect to and use WebSockets from right within the API Reference (check one of Hume's WebSockets [here](https://dev.hume.ai/reference/empathic-voice-interface-evi/chat/chat)).\
\
<Frame caption="Click 'Play' to open the WebSocket Playground">\
  <img src="file:0c5c04a5-dcd6-43e2-b6cd-21570026885a" alt="WebSocket Playground" />\
</Frame>\
\
\
# Errors in Fern Definition\
\
> Add errors representing failed responses from API endpoints in Fern Definition.\
\
Errors represent failed (non-200) responses from endpoints.\
\
An error has:\
\
* An HTTP status code\
* A body type *(Optional)*\
\
<CodeBlock title="user.yml">\
  ```yaml\
  errors:\
    UserNotFoundError:\
      status-code: 404\
      type: UserNotFoundErrorBody\
\
  types:\
    UserNotFoundErrorBody:\
      properties:\
        requestedUserId: string\
  ```\
</CodeBlock>\
\
\
# Imports in Fern Definition\
\
> Use imports to reference API types and errors from other Fern Definition files.\
\
Imports allow you to reference types and errors from other files.\
\
```yaml title="person.yml"\
types:\
  Person: ...\
```\
\
```yaml title="family.yml"\
imports:\
  person: ./path/to/person.yml\
types:\
  Family:\
    properties:\
      people: list<person.Person> # use an imported type\
```\
\
Note that you can only import files that exist in your Fern Definition (i.e., in the same `definition/` folder).\
\
\
# Examples in Fern Definition\
\
> Use Fern Definition to add API examples that are shown in comments of SDKs, API Reference documentation, and a Postman collection.\
\
You can add examples for types and endpoints. Examples are shown as\
comments in your SDKs, in the request & response of your documentation,\
and in a Postman Collection.\
\
## Validation\
\
The Fern CLI validates that your examples match the expected types. The following won't compile:\
\
```yaml\
types:\
  UserId:\
    type: integer\
    examples:\
      - value: hello # not an integer\
```\
\
```bash CLI Error Message\
[api]: example.yml -> types -> UserId -> examples[0]\
       Expected example to be an integer. Example is: "hello"\
```\
\
## Referencing examples\
\
You can reference an example from another type, endpoint, or error.\
\
Just like types, you can compose examples. To reference an example from another\
type, use `$`.\
\
```yaml \{14\}\
types:\
  UserId:\
    type: integer\
    examples:\
      - name: Example1\
        value: user-id-123\
\
  User:\
    properties:\
      id: UserId\
      name: string\
    examples:\
      - value:\
          id: $UserId.Example1\
          name: Jane Smith\
```\
\
## Examples for types\
\
### Objects\
\
```yml\
types:\
  ShipTo:\
    properties:\
      street1: string\
      street2: optional<string>\
      city: string\
      state: string\
      postalCode: string\
      country: Country\
      isResidential: boolean\
    examples:\
      - name: WhiteHouse\
        value:\
          street1: 1600 Pennsylvania Avenue NW\
          city: Washington DC\
          state: Washington DC\
          postalCode: "20500"\
          country: US\
          isResidential: true\
      - name: EmpireStateBuilding\
        value:\
          street1: 350 5th Ave\
          street2: Attn: Maintenance Department\
          city: New York\
          state: NY\
          postalCode: "10118"\
          country: US\
          isResidential: false\
```\
\
<CodeBlock title="Generated TypeScript SDK">\
  ```typescript\
  /**\
   * Represents a shipping address.\
   * \
   * The White House address\
   * @example \{\
   *  street1: "1600 Pennsylvania Avenue NW",\
   *  city: "Washington DC",\
   *  state: "Washington DC",\
   *  postalCode: "20500",\
   *  country: "US",\
   *  isResidential: true\
   * \}\
   * \
   * * The Empire State Building address\
   * @example \{\
   *  street1: "350 5th Ave",\
   *  street2: "Attn: Maintenance Department",\
   *  city: "New York",\
   *  state: "NY",\
   *  postalCode: "10118",\
   *  country: "US",\
   *  isResidential: false\
   * \}\
   */\
  type ShipTo = \{\
    street1: string;\
    street2?: string;\
    city: string;\
    state: string;\
    postalCode: string;\
    country: Country;\
    isResidential: boolean;\
  \};\
  ```\
</CodeBlock>\
\
### Lists\
\
```yml\
 Shipments:\
    type: list<ShipmentStatus>\
    examples:\
      - name: Default\
        value:\
          - status: "InTransit"\
            estimatedDeliveryDate: "2024-01-11"\
          - status: "Delivered"\
            estimatedDeliveryDate: "2024-01-13"\
```\
\
### Unions\
\
#### Discriminated union\
\
```yml\
types:\
  Animal:\
    union:\
      dog: Dog\
      cat: Cat\
    examples:\
      - value:\
          type: dog\
          likesToWoof: true\
  Dog:\
    properties:\
      likesToWoof: boolean\
  Cat:\
    properties:\
      likesToMeow: boolean\
```\
\
<CodeBlock title="Generated TypeScript SDK">\
  ```typescript\
  /**\
   * Represents an animal, which can be either a Dog or a Cat.\
   *\
   * Example of a Dog:\
   * @example \{\
   *  type: "dog",\
   *  likesToWoof: true\
   * \}\
   */\
  type Animal = Dog | Cat;\
  ```\
</CodeBlock>\
\
#### Undiscriminated union\
\
```yml\
types:\
  Animal:\
    discriminated: false\
    union:\
      - Dog\
      - Cat\
    examples:\
      - value:\
          likesToMeow: true\
  Dog:\
    properties:\
      likesToWoof: boolean\
  Cat:\
    properties:\
      likesToMeow: boolean\
```\
\
<CodeBlock title="Generated TypeScript SDK">\
  ```typescript\
  /**\
   * Represents an Animal, which can be either a Dog or a Cat.\
   *\
   * Example of an Animal as a Cat:\
   * @example \{\
   *  likesToMeow: true\
   * \}\
   */\
  type Animal = Dog | Cat;\
  ```\
</CodeBlock>\
\
### Aliases\
\
```yml\
types:\
  UserId:\
    docs: A unique identifier for a user\
    type: string\
    examples:\
      - value: user-id-123\
```\
\
<CodeBlock title="Generated TypeScript SDK">\
  ```typescript\
  /** \
  * A unique identifier for a user * \
  * @example "user-id-123" \
  */ \
  type UserId = string; \
  ```\
</CodeBlock>\
\
## Examples for endpoints\
\
You can add examples of successful and error responses for your endpoints.\
Examples can reference the examples of types to avoid duplication.\
\
```yml\
service:\
  auth: true\
  base-path: ""\
  endpoints:\
    CreateShippingLabel:\
      docs: Create a new shipping label.\
      method: POST\
      path: /shipping\
      request: CreateShippingLabelRequest\
      response: ShippingLabel\
      errors:\
        - NotAuthorized\
        - InsufficientFunds\
      examples:\
        # A successful response that doesn't reference other examples.\
        - request:\
            orderId: "online_789"\
            weightInOunces: 5\
          response:\
            body:\
              orderId: "online_789"\
              weightInOunces: 5\
              trackingNumber: "1Z26W8370303469306"\
              price: 2.50\
\
        # A successful response that uses references.\
        - request: $CreateShippingLabelRequest.SuccessfulRequest\
          response:\
            body: $ShippingLabel.Default\
\
        # An error response.\
        - request: $CreateShippingLabelRequest.InsufficientFundsRequest\
          response:\
            error: InsufficientFunds\
            body: $InsufficientFundsBody.Default\
\
types:\
  CreateShippingLabelRequest:\
    properties:\
      orderId: string\
      weightInOunces: integer\
    examples:\
      - name: SuccessfulRequest\
        value:\
          orderId: "online_123"\
          weightInOunces: 13\
      - name: InsufficientFundsRequest\
        value:\
          orderId: "online_456"\
          weightInOunces: 2000\
\
  ShippingLabel:\
    properties:\
      orderId: string\
      weightInOunces: integer\
      trackingNumber: string\
      price: double\
    examples:\
      - name: Default\
        value:\
          orderId: "online_123"\
          weightInOunces: 13\
          trackingNumber: "1Z12345E0205271688"\
          price: 12.35\
\
  InsufficientFundsBody:\
    properties:\
      message: string\
    examples:\
      - name: Default\
        value:\
          message: "Insufficient funds to create shipping label."\
\
errors:\
  NotAuthorized:\
    status-code: 401\
  InsufficientFunds:\
    status-code: 422\
    type: InsufficientFundsBody\
```\
\
## Examples for path parameters\
\
```yml\
service:\
  auth: true\
  base-path: ""\
  endpoints:\
    TrackShipment:\
      docs: Track the status of a shipment.\
      method: GET\
      path: /shipping/\{trackingNumber\}\
      path-parameters: \
        trackingNumber: string\
      response: ShipmentStatus\
      examples:\
        - path-parameters: \
            trackingNumber: "1Z26W8370303469306"\
          response:\
            body:\
              status: "InTransit"\
              estimatedDeliveryDate: "2024-01-11"\
```\
\
\
# Audiences in Fern Definition\
\
> Use audiences in your Fern Definition to segment your API for different groups of consumers.\
\
Audiences are a useful tool for segmenting your API for different consumers. You can configure your Fern Docs to publish documentation specific to an `Audience`. You can use [audiences in your OpenAPI Specification](/learn/api-definition/openapi/audiences), too.\
\
Common examples of audiences include:\
\
* Internal consumers (e.g., frontend developers who use the API)\
* Beta testers\
* Customers\
\
By default, if no audience is specified, it will be accessible to all consumers.\
\
## Configuration\
\
The Fern Definition has a first-class concept for marking different endpoints, types, and properties for different audiences.\
\
To use audiences in your Fern Definition, add them to `api.yml`.\
\
In the example below, we have created audiences for `internal`, `beta`, and `customer` groups:\
\
```yaml title='api.yml' \{2-5\}\
name: api \
audiences: \
  - internal \
  - beta \
  - customers\
```\
\
## Audiences for endpoints\
\
To mark an endpoint for a particular consumer, add an `audience` with the relevant groups.\
\
In this example, the `sendEmail` endpoint is only available to internal consumers:\
\
```yaml title='user.yml' \{6-7\}\
service:\
  base-path: /users\
  auth: true\
  endpoints:\
    sendEmail:\
      audiences:\
        - internal\
      path: /send-email\
      ...\
```\
\
## Audiences for types\
\
Types can also be marked for different audiences.\
\
In this example, the `Email` type is available to internal and beta consumers:\
\
```yaml title='user.yml' \{5-7\}\
Email: \
  properties:\
    subject: string\
    body: optional<string>\
  audiences: \
    - internal\
    - beta\
```\
\
## Audiences for properties\
\
Properties of a type can also be marked for different audiences.\
\
In this example, the `to` property is available to beta consumers only:\
\
```yaml title='user.yml' \{8-9\}\
Email: \
  properties:\
    subject: string\
    body: optional<string>\
    to: \
      type: string\
      docs: The recipient of the email\
      audiences: \
        - beta\
```\
\
## Audiences for SDKs\
\
In `generators.yml`, you can apply audience filters so that only certain\
endpoints are passed to the generators.\
\
The following example configures the SDKs to filter for `customers`:\
\
```yaml title='generators.yml' \{3-4\}\
groups:\
  external:\
    audiences:\
      - customers\
    generators: \
    ...\
```\
\
## Audiences with docs\
\
If generating Fern Docs, update your `docs.yml` configuration to include your audiences.\
\
The following example shows how to configure your `docs.yml` to publish documentation for the `customers` audience:\
\
<CodeBlock title="docs.yml">\
  ```yaml \{3-4\}\
  navigation:\
    - api: API Reference\
      audiences:\
        - customers\
  ```\
</CodeBlock>\
\
\
# Availability in Fern Definition\
\
> Add availability to Fern Definition API services, endpoints, types, or properties to indicate their release status.\
\
You can add `availability` to an endpoint, type, or property within your Fern Definition.\
\
Availability can be:\
\
* `in-development` which means it is being worked on; will show a `Beta` tag\
* `pre-release` which means it is available; will show a `Beta` tag\
* `deprecated` which means it will be removed in the future; will show a `Deprecated` tag\
* `generally-available` which means it is stable and available for use; will show a `GA` tag\
\
## Endpoint\
\
<CodeBlock title="pet.yml">\
  ```yaml \{6\}\
  service:\
    base-path: /pet\
    auth: true\
    endpoints:\
      add:\
        availability: deprecated\
        display-name: Add pet\
        docs: Add a new Pet to the store\
        method: POST\
        path: ""\
        request: AddPetRequest\
        response: Pet\
  ```\
</CodeBlock>\
\
In Fern Docs, this will look like:\
\
<Frame>\
  ![Screenshot showing a deprecated tag next to an endpoint in API Reference docs](https://fern-image-hosting.s3.amazonaws.com/endpoint-deprecated.png)\
</Frame>\
\
## Type\
\
<CodeBlock title="pet.yml">\
  ```yaml \{15\}\
    Pet:\
      properties:\
        id: \
          type: integer\
          docs: A unique ID for the Pet\
        name: \
          type: string\
          docs: The first name of the Pet\
        photoUrls: \
          type: list<string>\
          docs: A list of publicly available URLs featuring the Pet\
          availability: generally-available\
        category: \
          type: optional<Category>\
          availability: pre-release\
\
    Category:\
      properties:\
        id: optional<integer>\
        name: optional<string>\
  ```\
</CodeBlock>\
\
In Fern Docs, this will look like:\
\
<Frame>\
  ![Screenshot showing a beta tag next to a type in API Reference docs](https://fern-image-hosting.s3.amazonaws.com/type-beta.png)\
</Frame>\
\
## Property\
\
<CodeBlock title="pet.yml">\
  ```yaml \{12\}\
    Pet:\
      properties:\
        id: \
          type: integer\
          docs: A unique ID for the Pet\
        name: \
          type: string\
          docs: The first name of the Pet\
        photoUrls: \
          type: list<string>\
          docs: A list of publicly available URLs featuring the Pet\
          availability: deprecated\
        category: optional<Category>\
  ```\
</CodeBlock>\
\
In Fern Docs, this will look like:\
\
<Frame>\
  ![Screenshot showing a deprecated tag next to a type's property in API Reference docs](https://fern-image-hosting.s3.amazonaws.com/property-deprecated.png)\
</Frame>\
\
\
# The api.yml configuration file\
\
> The api.yml file contains general API configuration when using the Fern Definition format.\
\
A `fern/` folder has a special file called `api.yml`, which includes all the API-wide configuration.\
\
```bash \{5\}\
fern/\
\uc0\u9500 \u9472  fern.config.json\
\uc0\u9500 \u9472  generators.yml\
\uc0\u9492 \u9472  definition/\
  \uc0\u9500 \u9472  api.yml\
  \uc0\u9500 \u9472  pet.yml\
  \uc0\u9500 \u9472  store.yml\
  \uc0\u9492 \u9472  user.yml\
```\
\
## API name\
\
This name is used to uniquely identify your API in your organization. If you just have one API, then `api` is a sufficient name.\
\
<CodeBlock title="api.yml">\
  ```yaml\
  name: api\
  ```\
</CodeBlock>\
\
## API description\
\
You can define a top level API description. This description will come through in the OpenAPI Specification and Postman collection.\
\
<CodeBlock title="api.yml">\
  ```yaml \{2-4\}\
  name: api\
  docs: | \
    ## Header\
    This API provides access to...\
  ```\
</CodeBlock>\
\
## API version\
\
You can define your header-based API versioning scheme, such as an `X-API-Version`. The supported versions\
and default value are specified like so:\
\
<CodeBlock title="api.yml">\
  ```yaml\
  version:\
    header: X-API-Version\
    default: "2.0.0"\
    values:\
      - "1.0.0"\
      - "2.0.0"\
      - "latest"\
  ```\
</CodeBlock>\
\
\
# Environments\
\
> List environments like production, staging, and development.\
\
You can specify the environments where your server is deployed.\
\
## Single URL environments\
\
<CodeBlock title="api.yml">\
  ```yaml\
  name: api\
  environments:\
    Production: https://www.yoursite.com\
    Staging:\
      docs: This staging environment is helpful for testing!\
      url: https://www.staging.yoursite.com\
  ```\
</CodeBlock>\
\
## Multiple URLs per environment\
\
You can specify multiple URLs per environment. This is helpful if you have a\
microservice architecture, and you want a single SDK to interact with multiple\
servers.\
\
<CodeBlock title="api.yml">\
  ```yaml\
  environments:\
    Production:\
      urls:\
        Auth: https://auth.yoursite.com\
        Plants: https://plants.yoursite.com\
    Staging:\
      urls:\
        Auth: https://auth.staging.yoursite.com\
        Plants: https://plants.staging.yoursite.com\
  ```\
</CodeBlock>\
\
If you choose to use this feature, you must specify a `url` for each service you define:\
\
<CodeBlock title="auth.yml">\
  ```yaml\
  service:\
    url: Auth\
    base-path: /auth\
    ...\
  ```\
</CodeBlock>\
\
## Default environment\
\
You can also provide a default environment:\
\
<CodeBlock title="api.yml">\
  ```yaml\
  name: api\
  environments:\
    Production: https://www.yoursite.com\
    Staging:\
      docs: This staging environment is helpful for testing!\
      url: https://www.staging.yoursite.com\
  default-environment: Production\
  ```\
</CodeBlock>\
\
<Note>\
   By providing a default environment, the generated SDK will be setup to hit that URL out-of-the-box. \
</Note>\
\
## Base path\
\
If you would like all of your endpoints to be prefixed with a path, use `base-path`.\
\
In the example below, every endpoint is prefixed with a `/v1`:\
\
```yaml api.yml\
name: api\
base-path: /v1\
```\
\
## Audiences\
\
If you have listed environments that you want to filter, you can leverage audiences.\
\
<CodeBlock title="api.yml">\
  ```yaml\
  audiences:\
    - public\
\
  environments:\
    Dev: \
      url: https://dev.com\
    Prod: \
      url: https://rewards-api.getkard.com\
      audiences:\
        - external\
  ```\
</CodeBlock>\
\
\
# Global Configuration\
\
> Specify global headers, path parameters or query parameters meant to be included on every request.\
\
The `api.yml` configuration supports global configuration like headers and path parameters.\
\
## Global headers\
\
You can specify headers that are meant to be included on every request:\
\
<CodeBlock title="api.yml">\
  ```yaml\
  name: api\
  headers:\
    X-App-Id: string\
  ```\
</CodeBlock>\
\
## Global path parameters\
\
You can specify path parameters that are meant to be included on every request:\
\
<CodeBlock title="api.yml">\
  ```yaml\
  name: api\
  base-path: /\{userId\}/\{orgId\}\
  path-parameters:\
    userId: string\
    orgId: string\
  ```\
</CodeBlock>\
\
### Overriding the base path\
\
If you have certain endpoints that do not live at the configured `base-path`, you can\
override the `base-path` at the endpoint level.\
\
```yml imdb.yml \{5\}\
service: \
  endpoints: \
    getMovie: \
      method: POST\
      base-path: "override/\{arg\}"\
      path: "movies/\{movieId\}"\
      path-parameters: \
        arg: string\
```\
\
## Global query parameters\
\
You cannot yet specify query parameters that are meant to be included on every request.\
If you'd like to see this feature, please upvote [this issue](https://github.com/fern-api/fern/issues/2930).\
\
\
# Errors\
\
> Specify error types and schemas\
\
In order to generate SDKs idiomatically, Fern needs to know how to differentiate\
between different errors when parsing an endpoint response.\
\
### Discriminate by status code\
\
You can specify Fern to discriminate by status code. This means on each\
endpoint, every error that's listed must have a different HTTP status code.\
\
<CodeBlock title="api.yml">\
  ```yaml\
  name: api\
  error-discrimination:\
    strategy: status-code\
  ```\
</CodeBlock>\
\
### Discriminate by error name\
\
You can specify Fern to discriminate by error name. If you select this strategy,\
then Fern will assume that every error response has an extra property denoting\
the error name.\
\
If you use Fern to generate server-side code, then this option provides\
the most flexibility. Otherwise, you'll probably want to use the status code\
discrimination strategy.\
\
<CodeBlock title="api.yml">\
  ```yaml\
  name: api\
  error-discrimination:\
    strategy: property\
    property-name: errorName\
  ```\
</CodeBlock>\
\
### Global errors\
\
You can import and list errors that will be thrown by every endpoint.\
\
<CodeBlock title="api.yml">\
  ```yaml\
  imports:\
    commons: commons.yml\
\
  errors:\
    - commons.NotFoundError\
    - commons.BadRequestError\
  ```\
</CodeBlock>\
\
\
# Packages in Fern Definition\
\
> Fern Definition enables the reuse of API type and error names across packages, and can configure the structure of your API documentation.\
\
## What is a package?\
\
Every folder in your API definition is a package.\
\
<CodeBlock title="Example of package and nested package">\
  ```bash\
  fern/\
  \uc0\u9500 \u9472  fern.config.json\
  \uc0\u9500 \u9472  generators.yml\
  \uc0\u9492 \u9472  definition/ # <--- root package\
    \uc0\u9500 \u9472  api.yml\
    \uc0\u9500 \u9472  projects.yml\
    \uc0\u9492 \u9472  roles/ # <--- nested package\
      \uc0\u9492 \u9472  admin.yml\
  ```\
</CodeBlock>\
\
The generated SDK will match the hierarchy of your API definition.\
\
<CodeBlock title="Generated SDK">\
  ```ts\
  const client = new Client();\
\
  // calling endpoint defined in projects.yml\
  client.projects.get();\
\
  // calling endpoint defined in roles/admin.yml\
  client.roles.admin.get();\
  ```\
</CodeBlock>\
\
## Package configuration\
\
Each package can have a special definition file called `__package__.yml`. Like any\
other definition file, it can contain [imports](/learn/api-definition/fern/imports),\
[types](/learn/api-definition/fern/types), [endpoints](/learn/api-definition/fern/endpoints),\
and [errors](/learn/api-definition/fern/errors).\
\
Endpoints in `__package__.yml` will appear at the root of the package.\
For example, the following generated SDK:\
\
<CodeBlock title="Generated SDK">\
  ```ts\
  const client = new Client();\
\
  client.getProjects();\
  ```\
</CodeBlock>\
\
would have a `fern/` folder:\
\
<CodeBlock title="fern/">\
  ```bash \{5\}\
  fern/\
  \uc0\u9500 \u9472  fern.config.json\
  \uc0\u9500 \u9472  generators.yml\
  \uc0\u9492 \u9472  definition/\
    \uc0\u9500 \u9472  __package__.yml\
    \uc0\u9492 \u9472  roles.yml\
  ```\
</CodeBlock>\
\
that contains the following `__package__.yml`:\
\
<CodeBlock title="__package__.yml">\
  ```yaml\
  service:\
    base-path: ""\
    auth: false\
    endpoints:\
      getProjects:\
        method: GET\
        path: ""\
        response: list<Project>\
  ```\
</CodeBlock>\
\
## Namespacing\
\
Each package has its own namespace. This means you can reuse type names and\
error names across packages.\
\
This is useful when versioning your APIs. For example, when you want to\
increment your API version, you can copy the existing API\
to a new package and start making changes. If the new API version reuses\
certain types or errors, that's okay because the two APIs live in different\
packages.\
\
<CodeBlock title="Versioning example">\
  ```bash\
  fern/\
  \uc0\u9500 \u9472  fern.config.json\
  \uc0\u9500 \u9472  generators.yml\
  \uc0\u9492 \u9472  definition/\
    \uc0\u9500 \u9472  api.yml\
    \uc0\u9492 \u9472  roles/\
        \uc0\u9492 \u9472  v1/\
          \uc0\u9492 \u9472  admin.yml # type names can overlap with v2/admin.yml\
        \uc0\u9492 \u9472  v2/\
          \uc0\u9492 \u9472  admin.yml\
  ```\
</CodeBlock>\
\
## Navigation\
\
`__package__.yml` also allows you to configure the navigation order\
of your services. This is relevant when you want to control the display\
of your documentation.\
\
For example, let's say you have the following `fern/` folder:\
\
<CodeBlock title="fern/">\
  ```bash\
  fern/\
  \uc0\u9500 \u9472  fern.config.json\
  \uc0\u9500 \u9472  generators.yml\
  \uc0\u9492 \u9472  definition/\
    \uc0\u9500 \u9472  projects.yml\
    \uc0\u9500 \u9472  roles.yml\
    \uc0\u9492 \u9472  users.yml\
  ```\
</CodeBlock>\
\
Your API will be sorted alphabetically: projects, roles, then users. If you\
want to control the navigation, you can add a `__package__.yml` file\
and configure the order:\
\
<CodeBlock title="fern/">\
  ```bash\
  fern/\
  \uc0\u9500 \u9472  fern.config.json\
  \uc0\u9500 \u9472  generators.yml\
  \uc0\u9492 \u9472  definition/\
    \uc0\u9500 \u9472  __package__.yml # <--- New File\
    \uc0\u9500 \u9472  projects.yml\
    \uc0\u9500 \u9472  roles.yml\
    \uc0\u9492 \u9472  users.yml\
  ```\
</CodeBlock>\
\
<CodeBlock title="__package__.yml">\
  ```yaml\
  navigation: \
    - users.yml\
    - roles.yml\
    - projects.yml\
  ```\
</CodeBlock>\
\
\
# Depending on other APIs\
\
> Import API Definitions to generate unified SDKs\
\
Fern allows you to import other APIs into your API.\
\
This is often useful if:\
\
* you want to reuse another API's types in your API\
* you want to combine multiple microservices' APIs into one SDK (similar to the AWS SDK)\
\
## Registering the dependency API\
\
The first step is to **register** the API you want to depend on. To do this, use\
the `register` command:\
\
```\
$ fern register\
[some-dependency]: Uploading definition...\
[some-dependency]: Registered @fern/some-dependency:0.0.1\
```\
\
## Depending on the registered API\
\
To add a dependency on another API, you must add a `dependencies.yml` to declare which\
APIs you wish to depend on.\
\
```bash \{4\}\
fern/\
\uc0\u9500 \u9472  fern.config.json\
\uc0\u9500 \u9472  generators.yml\
\uc0\u9500 \u9472  dependencies.yml\
\uc0\u9492 \u9472  definition/\
  \uc0\u9500 \u9472  api.yml\
  \uc0\u9500 \u9472  imdb.yml\
```\
\
Your `dependencies.yml` has a list of all the APIs you wish to depend:\
\
```yaml dependencies.yml \
dependencies:\
   "@fern/some-dependency": "0.0.1"\
```\
\
Next, you need create a folder in your Fern Definition to house the dependency. Inside the folder, create a special file\
`__package__.yml` which specifies the dependency and version you want to add.\
\
```bash \{8-9\}\
fern/\
\uc0\u9500 \u9472  fern.config.json\
\uc0\u9500 \u9472  generators.yml\
\uc0\u9500 \u9472  dependencies.yml\
\uc0\u9492 \u9472  definition/\
  \uc0\u9500 \u9472  api.yml\
  \uc0\u9500 \u9472  imdb.yml\
  \uc0\u9492 \u9472  my-folder\
    \uc0\u9492 \u9472  __package__.yml  \
```\
\
```yaml __package__.yml\
export:\
  dependency: "@fern/some-dependency"\
```\
\
When you generate the SDK with `fern generate`, the `__package__.yml` file will\
effectively be replaced with the API you're depending on.\
\
\
# Export from Fern Definition to OpenAPI\
\
> Export your Fern Definition files to OpenAPI using Fern's OpenAPI generator.\
\
To prevent lock-in to the Fern Definition format, we provide a generator that will export your Fern Def files to OpenAPI 3.1.\
This lets you switch to using OpenAPI at any time, or use your API definition with OpenAPI tools.\
To convert your Fern Definition to OpenAPI, use the `fern-openapi` generator.\
\
Update your `generators.yml` file:\
\
<CodeBlock title="generators.yml">\
  ```yaml\
  - name: fernapi/fern-openapi\
    version: 0.0.31\
    config:\
      format: yaml # options are yaml or json\
    output:\
      location: local-file-system\
      path: ../openapi # relative path to output location\
  ```\
</CodeBlock>\
\
\
# SDK Overview\
\
> Generate idiomatic SDKs in multiple programming languages\
\
Let Fern do the heavy lifting of generating and publishing client libraries so your team can focus on building the API.\
\
## Learn more\
\
<CardGroup cols=\{2\}>\
  <Card title="Supported Languages" href="/learn/sdks/introduction/language-support" icon="regular globe">\
    Explore the full list of Fern's supported languages.\
  </Card>\
\
  <Card title="Book a Demo" href="https://buildwithfern.com/contact" icon="regular calendar">\
    See Fern in action with a personalized demo.\
  </Card>\
\
  <Card title="Overview Capabilities" href="/learn/sdks/capabilities/strongly-typed" icon="regular book">\
    Learn more about advanced features supported by Fern's SDk generation.\
  </Card>\
\
  <Card title="Generate your first SDK" href="/learn/sdks/guides/generate-your-first-sdk" icon="regular rocket">\
    Follow our step-by-step guide to generate your first SDK in minutes.\
  </Card>\
</CardGroup>\
\
\
# Language support\
\
Fern supports generating SDKs in several different programming languages. Each SDK generator is written by a language expert and is officially maintained by the Fern team.\
\
### Generally Available\
\
<CardGroup cols=\{3\}>\
  <Card title="TypeScript" icon="brands node-js" />\
\
  <Card title="Python" icon="brands python" />\
\
  <Card title="Go" icon="brands golang" />\
\
  <Card title=".NET" icon="brands microsoft" />\
\
  <Card title="Java" icon="brands java" />\
\
  <Card title="Ruby" icon="gem" />\
\
  <Card title="PHP" icon="brands php" />\
</CardGroup>\
\
### Coming Soon\
\
<CardGroup cols=\{3\}>\
  <Card title="Swift" icon="brands swift" />\
\
  <Card title="Rust" icon="brands rust" />\
\
  <Card title="Terraform" icon="cloud" />\
\
  <Card title="CLI" icon="terminal" />\
</CardGroup>\
\
<Warning title="Get early access">\
  Please reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com) if you're interested in our generators that are coming soon.\
</Warning>\
\
\
# December 8, 2024\
\
## 4.3.9\
\
**`(fix):`** Fix indentation in generated README.md sections to ensure proper formatting and readability.\
\
\
# November 20, 2024\
\
## 4.3.8\
\
**`(fix):`** Include content-type headers when available as part of endpoint request generation.\
\
\
# November 19, 2024\
\
## 4.3.7\
\
**`(fix):`** Update multipart endpoint generation to propertly omit optional body parameters.\
\
\
# November 15, 2024\
\
## 4.3.6\
\
**`(fix):`** Fix README.md and reference.md generation.\
\
\
# November 14, 2024\
\
## 4.3.5\
\
**`(fix):`** Update README.md snippet builder to omit invalid snippets during readme config generation.\
\
\
# November 13, 2024\
\
## 4.3.4\
\
**`(fix):`** Update shared http\\_client.py to remove omitted entries during file upload requests.\
\
\
# October 21, 2024\
\
## 4.3.1\
\
**`(feat):`** Requests for file download will now allow users to pass in a `chunk_size` option that allows them to receive chunks of a specific size\
from the resultant `iter_bytes` invocation on the response byte stream.\
\
Concretely, a user would leverage the following:\
\
```python\
client.download(\
  ...,\
  request_options=\{\
    "chunk_size": 1024    # 1MB\
  \}\
)\
```\
\
\
# October 11, 2024\
\
## 4.2.8\
\
**`(fix):`** The snippet writer now correctly handles base64 strings.\
\
\
# September 28, 2024\
\
## 4.2.7\
\
**`(fix):`** The generated README will now have a section that links to the generated\
SDK Reference (in `reference.md`).\
\
```md\
## Reference\
\
A full reference for this library can be found [here](./reference.md).\
```\
\
\
# September 26, 2024\
\
## 4.2.7-rc2\
\
**`(fix):`** Pydantic utilities now correctly handles cases where you have a Pydantic model, with a list of pydantic models as a field, where those models have literals.\
Effectively, `deep_union_pydantic_objects` now handles lists of objects and merges them appropriately.\
\
\
# September 23, 2024\
\
## 4.2.7-rc0\
\
**`(fix):`** Dynamic header suppliers, as used within the OAuth provider are now invoked on every request, not just the first.\
This was a regression introduced within an earlier version that is now fixed. As a results of this fix, the `refresh_token` is now correctly refreshed.\
\
\
# September 20, 2024\
\
## 4.2.5\
\
**`(fix):`** Parameters of file upload functions now default to OMIT, not None, so that the SDK appropriately\
filters out unset parameters, while still allowing for user specified None values.\
\
\
# September 17, 2024\
\
## 4.2.4\
\
**`(fix):`** Datetime examples are generated correctly once again.\
The `pydantic_utilites` file is python 3.8 compatible.\
\
\
# September 16, 2024\
\
## 4.2.2\
\
**`(fix):`** The content type of non-file properties is now respected for multipart\
requests. For example, if you have a type called `metadata` that has the\
content type `application/json`, then it will be sent as:\
\
```python\
"metadata": (None, json.dumps(jsonable_encoder(metadata)), "application/json"),\
```\
\
\
# September 15, 2024\
\
## 4.2.1\
\
**`(fix):`** When the generator runs bash commands such as `poetry install` and there is a failure,\
now the `stderr` and `stdout` is logged to help improve user debugging.\
\
\
# September 13, 2024\
\
## 4.0.0\
\
**`(fix):`** Generated tests that expect an empty result when they are of type `text` (not JSON) now appropriately expect an empty string instead of `None` for async functions as well.\
Version 3.3.4 fixed this for sync functions only, which was a bug.\
\
\
# September 12, 2024\
\
## 4.0.0-rc9\
\
**`(fix):`** All Pydantic V2 warnings have been resolved\
\
### What's been fixed\
\
* json\\_encoders have been removed from Pydantic V2, and replaced with a `model_serializer` method.\
* additional model construction functions have been added when not leveraging pydantic field aliases to allow users to construct a model from JSOn without the need for dealiasing the object themselves.\
\
\
# September 11, 2024\
\
## 4.0.0-rc6\
\
**`(fix):`** Pydantic models now call update forward refs on non-uion circular references. This\
prevents runtime errors in certain cases where types self reference itself through\
a union.\
\
\
# September 10, 2024\
\
## 4.0.0-rc3\
\
**`(fix):`** Pydantic models now call update forward refs on non-uion circular references. This\
prevents runtime errors in certain cases where types self reference itself through\
a union.\
\
\
# September 6, 2024\
\
## 4.0.0-rc1\
\
**`(fix):`** Update .dict calls in Pydantic V2 to be back to pre-3.10.4 logic.\
\
### What's been fixed\
\
* Pydantic V2 `.dict` calls are updated to be back to pre-3.10.4 logic. This is fix a regression where nested literals were being omitted due to the Pydantic V2 serializers not respecting the recursive .dict logic, as Pydantic V2 shells out `model_dump` calls to Rust library and serializers, as opposed to recursively calling `model_dump`.\
  It is expected that performance will not be degraded given the Rust-based serializers have optimized performance, compared to the Pydantic V1 .dict approach.\
\
\
# September 5, 2024\
\
## 4.0.0-rc0\
\
**`(fix):`** Rerelease 3.11.0-rc0 as a major version, with a configuration flag to disable the behavior (`use_pydantic_field_aliases`), defaulted to `true` to preserve existing behavior.\
\
**`(internal):`** The generator now shares "as is" files with Pydantic and FastAPI generators.\
\
### What's been fixed\
\
* Rerelease 3.11.0-rc0 as a major version, with a configuration flag to disable the behavior (`use_pydantic_field_aliases`), defaulted to `false` to introduce the break on a major version.\
  To maintain parity with pre-3.11.0 behavior, update the flag to `true`:\
\
  ```yaml\
  - name: fernapi/fern-python-sdk\
    version: 4.0.0-rc0\
    config:\
      pydantic_config:\
        use_pydantic_field_aliases: true\
  ```\
\
\
# September 4, 2024\
\
## 3.11.0-rc0\
\
**`(chore):`** Remove Pydantic field aliases and leverage an internal representation.\
\
### What's been fixed\
\
* Pydantic field aliases are removed and replaced with an internal representation. This allows for more robust handling of field aliases and prevents issues with Pydantic V2 and mypy.\
  Previously, you'd have for V1 and V2 compatibility in Pydantic, you'd want to conditionally apply the config class within the base model, however this would lead to mypy errors when filling out a model with it's field alias. To solve this, We used the deprecated `class Config`, regardless of the Pydantic version to satisfy mypy, which lead to warnings in the console.\
  Now, we've removed the field aliases and replaced them with an internal representation, which allows us to avoid pydantic config altogether.\
\
\
# September 2, 2024\
\
## 3.10.8\
\
**`(fix):`** Allow for fields prefixed with the name `model`, a silent break introduced in Pydantic V2.\
\
\
# August 28, 2024\
\
## 3.10.7\
\
**`(fix):`** When not leveraging mock integration tests, still run pytest over everything, not a specific directory.\
\
\
# August 16, 2024\
\
## 3.10.3\
\
**`(fix):`** Upgrade intermediate representation dependency to safely parse null unknown types.\
\
\
# August 14, 2024\
\
## 3.10.3\
\
**`(fix):`** Query encoding now appropriately takes arrays of deep objects into account.\
\
\
# August 13, 2024\
\
## 3.10.1\
\
**`(fix):`** If there are no autogenerated examples present, the Python SDK generator no longer fails.\
\
\
# August 9, 2024\
\
## 3.8.0\
\
**`(chore):`** Generated SDKs now use ruff for linting and formatting instead of Black.\
\
\
# August 8, 2024\
\
## 3.6.0\
\
**`(feat):`** The generator now respects returning nested properties from the returned object\
\
\
# August 5, 2024\
\
## 3.4.2\
\
**`(fix):`** The Python generator now instantiates `Any` types as `Optional[Any]` to be able to mitigate breaks in Pydantic V2.\
\
\
# August 4, 2024\
\
## 3.4.1\
\
**`(chore):`** Literal templates are generated if they are union members\
\
\
# August 2, 2024\
\
## 3.3.1\
\
**`(fix):`** Generated READMEs now reference RequestOptions as TypedDicts correctly.\
\
\
# August 1, 2024\
\
## 3.3.0-rc1\
\
**`(fix):`** TypedDict snippets now include literals where available.\
\
\
# July 31, 2024\
\
## 3.3.0-rc0\
\
**`(internal):`** Upgrade to IR 53.1.0\
\
### What's changed\
\
* Upgrade to IR 53.1.0\
* The Python generator now creates snippet templates for undiscriminated unions.\
\
\
# July 29, 2024\
\
## 3.2.0-rc1\
\
**`(fix):`** The generated README now imports `ApiError` as if it were from outside the module.\
\
\
# July 25, 2024\
\
## 3.2.0-rc0\
\
**`(feat):`** The Python SDK can now be generated with TypedDicts as inputs.\
\
### What's new\
\
* The Python SDK can now be generated such that inputs to requests are TypedDicts, instead of Pydantic models. This allows for consumers of the SDK to continue to have type hinting and autocomplete, but not need to import new object types when creating requests.\
\
\
# July 24, 2024\
\
## 3.0.0-rc2\
\
**`(fix):`** `update_forward_refs` no longer raises errors, preserving original behavior, pre-3.x.\
\
\
# July 23, 2024\
\
## 3.0.0-rc0\
\
**`(break):`** The generated models now support Pydantic V2 outright, it no longer uses `pydantic.v1` models.\
\
### What's changed\
\
* The generated models now support Pydantic V2 outright, it no longer uses `pydantic.v1` models.\
* Public fields previously prefixed with `_` are now prefixed with `f_` (Pydantic V2 does not allow for `_` prefixes on public fields and Python does not allow for a numeric prefix)\
\
### What's been removed\
\
* wrapped aliases outside of Pydantic V1\
* custom root validators outside of Pydantic V1\
\
\
# July 17, 2024\
\
## 2.15.5\
\
**`(fix):`** The generated python SDK Oauth client now no longer checks for an expiry when getting the access token if an expiry field is not configured.\
\
\
# July 16, 2024\
\
## 2.16.0\
\
**`(feat):`** The generated SDK now allows for specifying whether or not to generate `streaming` functions as overloaded functions or separate functions.\
\
\
# July 10, 2024\
\
## 2.15.2\
\
**`(fix):`** The generated python SDK no longer treats `set` as a reserved word for method names.\
\
\
# July 9, 2024\
\
## 2.15.1\
\
**`(fix):`** The unchecked base model no longer coerces None to a type.\
\
### What's been fixed\
\
* The unchecked base model no longer coerces None to a type.\
* The http client appropriately defaults empty fields within RequestOptions.\
\
\
# July 3, 2024\
\
## 2.15.0\
\
**`(feat):`** The generated python SDK now respects configured defaults from the API spec.\
\
\
# July 1, 2024\
\
## 2.14.0-rc2\
\
**`(chore):`** Async snippets now run the async function leveraging asyncio.run to be more copy-pastable.\
\
\
# June 27, 2024\
\
## 2.14.0-rc1\
\
**`(fix):`** The fix from 2.5.2 is now case-insentitive\
\
### What's been fixed\
\
* the fix from 2.5.2 is now case-insentitive Recap of 2.5.2: `Fix: Support `list`SDK method names instead of defaulting to`list\\_`.`\
\
\
# June 26, 2024\
\
## 2.14.0-rc0\
\
**`(feat):`** The Python SDK now generates an accompanying SDK reference (`reference.md`) for users to review the SDK methods at a glance within the SDK's GitHub repository.\
\
\
# June 25, 2024\
\
## 2.11.0-rc0\
\
**`(chore):`** Snippet templates now support auth variables within the root client.\
\
### What's changed\
\
* Improvement: The SDK now produces templates for the root clients within snippet-template.json. This allows users of the Templates API to pass in data for the auth variables present within the root client.\
\
\
# June 20, 2024\
\
## 2.9.10\
\
**`(fix):`** The generator now only specifies the readme location within pyproject.toml if one was successfully created.\
\
\
# June 19, 2024\
\
## 2.9.9\
\
**`(internal):`** The generator now consumes IRv46.\
\
\
# June 18, 2024\
\
## 2.9.8\
\
**`(chore):`** The python generator only adds a publish step in github actions if credentials are specified.\
\
\
# June 12, 2024\
\
## 2.9.7\
\
**`(fix):`** The unchecked base model stops special casing defaults and pydantic v2.\
\
\
# June 11, 2024\
\
## 2.9.6\
\
**`(fix):`** Offset based pagination is now 1-based, as opposed to 0 based\
\
### What's been fixed\
\
* Offset based pagination is now 1-based, as opposed to 0 based\
* The HTTP client now passes in additional body properties from the request options, even if the body is empty (regression from the client migration in 2.8.0)\
\
\
# June 10, 2024\
\
## 2.9.5\
\
**`(fix):`** Unions with elements that specify no properties are generated correctly.\
\
### What's been fixed\
\
* Unions with elements that specify no properties are generated correctly.\
* Unions with a single type now have a valid type alias (rather than an invalid `typing.Union`).\
\
\
# June 7, 2024\
\
## 2.9.4\
\
**`(fix):`** The unchecked base model now handles pulling the discriminant from a dict, not just a model/object.\
\
\
# June 6, 2024\
\
## 2.9.1\
\
**`(fix):`** The SDK removes unset query parameters from requests (regression from the client migration in 2.8.0)\
\
### What's been fixed\
\
* The SDK removes unset query parameters from requests (regression from the client migration in 2.8.0)\
* The SDK fixes it's type for `files` parameters to the http client (regression from the client migration in 2.8.0)\
\
\
# June 5, 2024\
\
## 2.9.0-rc1\
\
**`(fix):`** The new http client abstraction ensures a slash is postfixed to the baseurl\
\
\
# June 4, 2024\
\
## 2.8.1\
\
**`(fix):`** The parameter comment/documentation for timeouts on the root client now reflects the custom timeout passed through within configuration.\
\
\
# June 3, 2024\
\
## 2.8.0\
\
**`(chore):`** Endpoint function request logic has been abstracted into the request function of the wrapped httpx client.\
\
\
# May 31, 2024\
\
## 2.6.1\
\
**`(internal):`** this adds a back door token getter function to OAuth clients to better test the functionality.\
\
\
# May 30, 2024\
\
## 2.5.7\
\
**`(fix):`** tests now carry a type annotation for `expected_types` variable.\
\
\
# May 29, 2024\
\
## 2.5.5\
\
**`(fix):`** Auto-Pagination now respects optional return values\
\
### What's been fixed\
\
* Optional lists returned from pagination endpoints are now appropriately flattened such that the `Pager` return types are correctly `Pager[ListItem]` as opposed to `Pager[List[ListItem]]`.\
\
\
# May 28, 2024\
\
## 2.5.4\
\
**`(internal):`** Add typing library for dateutils in testing lib to satisfy mypy errors.\
\
\
# May 24, 2024\
\
## 2.5.3\
\
**`(chore):`** Stops specifying custom licenses manually, lets poetry handle adding them.\
\
\
# May 23, 2024\
\
## 2.5.0-rc2\
\
**`(fix):`** Do not attempt to run `fern test` in CI until the command is more widely rolled out.\
\
\
# May 22, 2024\
\
## 2.5.0-rc0\
\
**`(fix):`** This version addresses issues in unit test generation and reenables the creation of unit tests.\
\
\
# May 21, 2024\
\
## 2.3.0\
\
**`(chore):`** Users can now specify information that will appear in their pypi record.\
\
\
# May 20, 2024\
\
## 2.2.2\
\
**`(fix):`** Inline request parameters now deconflict in naming with the unnamed path parameter arguments.\
\
### What's been fixed\
\
* Inline request parameters now deconflict in naming with the unnamed path parameter arguments. Previously, when inlining request parameters into the method signature, we would not deconflict naming with the unnamed args preceeding them. Now, conflicting unnamed parameters are post-fixed with an "\\_".\
\
\
# May 17, 2024\
\
## 2.2.1\
\
**`(internal):`** The generator now uses the latest FDR SDK.\
\
\
# May 16, 2024\
\
## 2.2.0\
\
**`(chore):`** The generated SDK will now correctly encode deep object query parameters\
\
### What's changed\
\
* The generated SDK will now correctly encode deep object query parameters. For example, if you have an object `\{"test": \{"nested": "object"\}\}` as a query parameter, we will now encode it as `test[nested]=object`.\
\
\
# May 15, 2024\
\
## 2.1.1\
\
**`(chore):`** add enhanced snippet support for streaming endpoints.\
\
\
# May 14, 2024\
\
## 2.0.1\
\
**`(fix):`** The python generator now only excludes unset fields that are not required.\
\
### What's been fixed\
\
* the python generator previously used `exclude_unset` on pydantic models, however this would remove defaulted values. This change updates this to only exclude none fields that were not required.\
\
\
# May 9, 2024\
\
## 1.6.0-rc0\
\
**`(chore):`** You can now specify dev dependencies from your `generators.yml` file\
\
\
# May 2, 2024\
\
## 1.5.2-rc0\
\
**`(chore):`** The python generator now produces sync snippet templates, as opposed to just async templates as it was before\
\
\
# May 1, 2024\
\
## 1.5.1-rc1\
\
**`(fix):`** Improve formatting within snippet templates.\
\
### What's been fixed\
\
* Address formatting issues with snippet templates, we now strip newlines off OG snippets as well as plumb through indentation metadata to places that were previously missing it.\
\
\
# April 30, 2024\
\
## 1.5.0-rc0\
\
**`(feat):`** The generator now supports inlining top-level request parameters instead of requiring users create a request object.\
\
\
# April 29, 2024\
\
## 1.4.0\
\
**`(feat):`** keyword arguments are now ordered such that required params are ordered before optional params\
\
### What's changed\
\
* keyword arguments are now ordered such that required params are ordered before optional params. Note that since these are kwargs, this is a non-breaking change.\
* docstrings now match numpydoc/PEP257 format\
\
\
# April 26, 2024\
\
## 1.5.1-rc0\
\
**`(fix):`** Discriminated union variants that are objects now have inlined properties instead of extending a base type.\
\
\
# April 24, 2024\
\
## 1.4.0-rc3\
\
**`(fix):`** pin mypy dependency to 1.9.0 to prevent introducing upstream bugs\
\
### What's been fixed\
\
* Set `mypy` dev depenency in generated `pyproject.toml` to `1.9.0`. This prevents upstream `mypy` bugs from affecting user builds. Note that this is only a dev dependency, so it does not affect the behavior of the SDK.\
* Temporarily disable unit test generation.\
\
### What's changed\
\
* Improvement: Use named parameters for all `httpx` request params.\
\
\
# April 23, 2024\
\
## 1.4.0-rc2\
\
**`(fix):`** Initialize the OAuth token provider member variables to their default values before they are set.\
\
\
# April 22, 2024\
\
## 1.3.0-rc1\
\
**`(internal):`** add logging for python snippet template generation.\
\
\
# April 21, 2024\
\
## 1.3.0-rc0\
\
**`(feat):`** Beta: The generator now registers snippet templates which can be used for dynamic SDK code snippet generation.\
\
\
# April 10, 2024\
\
## 1.2.0-rc0\
\
**`(internal):`** Consume IR v38\
\
### What's new\
\
* The generator now depends on v38 of Intermediate Representation which requires the latest CLI. As part of this, the generator now supports server sent events using `httpx-sse`.\
\
\
# April 4, 2024\
\
## 1.1.0-rc1\
\
**`(fix):`** The generator no longer attempts to create a version file if Fern does not own generating the full package (e.g. in local generation).\
\
### What's been fixed\
\
* The generator no longer attempts to create a version file if Fern does not own generating the full package (e.g. in local generation). It's too confusing for to make the relevant changes to the package set up, and is also arguably not even needed in local generation.\
\
\
# April 3, 2024\
\
## 0.13.4\
\
**`(fix):`** revert changes introduced within 0.12.2\
\
### What's been fixed\
\
* revert the change from 0.13.2, the stream call returns a context manager, which is not awaited. The issue that this was meant to solve was actually fixed in version `0.12.2`.\
\
\
# April 2, 2024\
\
## 1.0.0\
\
**`(break):`** The python SDK now defaults new (breaking configuration) to introduce general improvements.\
\
### What's changed\
\
* Break: The python SDK now defaults new (breaking configuration) to introduce general improvements.\
* Improvement: The python SDK now supports specifying whether or not to follow redirects in requests by default, and exposes an option to override that functionality for consumers.\
\
\
# March 28, 2024\
\
## 0.13.2\
\
**`(fix):`** Asynchronous calls to `httpx.stream` are now awaited. This is applicable to any file download or JSON streaming (chat completion) endpoints.\
\
\
# March 26, 2024\
\
## 0.13.1\
\
**`(feat):`** discriminant values in unions are now defaulted such that callers no longer need to specify the discriminant\
\
\
# March 25, 2024\
\
## 0.13.0\
\
**`(feat):`** the python SDK now exposes it's version through `__version__` to match module standards and expectations.\
\
\
# March 22, 2024\
\
## 0.12.5\
\
**`(fix):`** the python SDK uses the timeout provided to the top level client as the default per-request\
\
### What's been fixed\
\
* the python SDK uses the timeout provided to the top level client as the default per-request, previously if there was no timeout override in the RequestOptions, we'd default to 60s, even if a timeout was provided at the client level.\
\
\
# March 19, 2024\
\
## 0.12.4\
\
**`(chore):`** Allow full forward compat with enums while keeping intellisense by unioning enum literals with `typing.AnyStr`.\
\
\
# March 18, 2024\
\
## 0.12.2\
\
**`(fix):`** Fix the returned type and value contained within the retrying wrapper for the HTTPX client (http\\_client.py).\
\
\
# March 14, 2024\
\
## 0.12.1\
\
**`(chore):`** Improves example generation and snippets for union types, as well as multi-url environments.\
\
### What's been fixed\
\
* Stringifies header arguments, HTTPX was previously hard failing for certain types\
\
### What's changed\
\
* Improves example generation and snippets for union types, as well as multi-url environments.\
\
\
# March 11, 2024\
\
## 0.12.0\
\
**`(feat):`** Auto-generated unit and integration tests against a mock server.\
\
### What's new\
\
* Beta: The SDK now generates tests leveraging auto-generated data to test typing, as well as wire-formatting (e.g. the SDKs are sending and receiving data as expected). This comes out of the box within the generated github workflow, as well as through the fern cli: `fern test --command "your test command"`.\
\
\
# March 8, 2024\
\
## 0.11.10\
\
**`(feat):`** Expose a feature flag to pass through additional properties not specified within your pydantic model from your SDK.\
\
### What's new\
\
* Expose a feature flag to pass through additional properties not specified within your pydantic model from your SDK. This allows for easier forward compatibility should your SDK drift behind your spec.\
\
\
# March 4, 2024\
\
## 0.11.9\
\
**`(chore):`** use docstrings instead of Pydantic field descriptions.\
\
\
# March 2, 2024\
\
## 0.11.8-rc1\
\
**`(feat):`** Introduces a `max_retries` parameter to the RequestOptions dict accepted by all requests.\
\
### What's changed\
\
* Beta: Introduces a `max_retries` parameter to the RequestOptions dict accepted by all requests. This parameter will retry requests automatically, with exponential backoff and a jitter. The client will automatically retry requests of a 5XX status code, or certain 4XX codes (429, 408, 409).\
\
\
# February 27, 2024\
\
## 0.11.7\
\
**`(feat):`** Introduces a flag `use_str_enums` to swap from using proper Enum classes to using Literals to represent enums.\
\
### What's changed\
\
* Introduces a flag `use_str_enums` to swap from using proper Enum classes to using Literals to represent enums. This change allows for forward compatibility of enums, since the user will receive the string back.\
\
\
# February 26, 2024\
\
## 0.11.6\
\
**`(feat):`** You can now specify envvars to scan for headers, not just auth scheme headers.\
\
\
# February 23, 2024\
\
## 0.11.4\
\
**`(fix):`** We now grab enum values appropriately when enums are within unions.\
\
\
# February 22, 2024\
\
## 0.11.3\
\
**`(fix):`** Transition from lists to sequences within function calls\
\
### What's been fixed\
\
* Transition from lists to sequences within function calls, this is a fix as a result of how mypy handles type variance. This fix is only for function calls as testing shows that we do not hit the same issue within mypy with list\\[union\\[\\*]] fields on pydantic objects.\
\
### What's changed\
\
* Improvement: The Python SDK generator now defaults to `require_optional_fields = False`. This means that any requests that have optional fields no longer require a user to input data (or a `None` value) in.\
\
\
# February 21, 2024\
\
## 0.11.2\
\
**`(feat):`** introduce configuration to flatten the directory structure\
\
### What's changed\
\
* Improvement (Beta): The Python generator now supports a configuration option called `improved_imports`.\
\
\
# February 20, 2024\
\
## 0.11.1\
\
**`(feat):`** Python now supports specifying files to auto-export from the root `__init__.py` file\
\
### What's changed\
\
* Python now supports specifying files to auto-export from the root `__init__.py` file, this means you can export custom classes and functions from your package for users to access like so:\
* Add a docstring for base clients to explain usage, example:\
\
\
# February 19, 2024\
\
## 0.10.3\
\
**`(fix):`** Several bugfixes were made to related to literal properties\
\
### What's been fixed\
\
* Several bugfixes were made to related to literal properties. If a literal is used as a query parameeter, header, path parameter, or request parameter, the user no longer has to explicitly pass it in.\
\
\
# February 18, 2024\
\
## 0.10.2\
\
**`(fix):`** The SDK always sends the enum wire value instead of the name of the enum.\
\
### What's been fixed\
\
* The SDK always sends the enum wire value instead of the name of the enum.\
* Revert #2719 which introduced additional issues with circular references within our Python types.\
\
\
# February 14, 2024\
\
## 0.10.1\
\
**`(feat):`** Add support for a RequestOptions object for each generated function within Python SDKs\
\
### What's changed\
\
* Add support for a RequestOptions object for each generated function within Python SDKs. This parameter is an optional final parameter that allows for configuring timeout, as well as pass in arbitrary data through to the request. RequestOptions is a TypedDict, with optional fields, so there's no need to instantiate an object, just pass in the relevant keys within a dict!\
\
\
# February 13, 2024\
\
## 0.10.0\
\
**`(break):`** The generator no longer supports Python 3.7\
\
### What's been removed\
\
* The generator no longer supports Python 3.7\
* The `backports` dependency has been removed\
\
\
# February 11, 2024\
\
## 0.9.0\
\
**`(feat):`** The SDK generator now supports whitelabelling\
\
### What's new\
\
* The SDK generator now supports whitelabelling. When this is turned on, there will be no mention of Fern in the generated code.\
\
\
# January 29, 2024\
\
## 0.8.3-rc0\
\
**`(fix):`** Increase recursion depth to allow for highly nested and complex examples\
\
### What's been fixed\
\
* Increase recursion depth to allow for highly nested and complex examples, this is a temporary solution while the example datamodel is further refined.\
\
\
# January 28, 2024\
\
## 0.8.2-rc0\
\
**`(fix):`** The Python SDK better handles cyclical references\
\
### What's been fixed\
\
* The Python SDK better handles cyclical references. In particular, cyclical references are tracked for undiscriminated unions, and update\\_forward\\_refs is always called with object references.\
\
\
# January 26, 2024\
\
## 0.8.1\
\
**`(feat):`** The generated SDK respects environment variables for authentication if specified\
\
### What's new\
\
* If the auth scheme has environment variables specified, the generated python client will scan those environment variables.\
\
\
# January 25, 2024\
\
## 0.8.0\
\
**`(fix):`** Enums in inlined requests send the appropriate value.\
\
\
# January 21, 2024\
\
## 0.7.7\
\
**`(internal):`** Initialize the changelog\
\
\
# November 21, 2024\
\
## 0.33.0\
\
**`(feat):`** Add support for the `inlinePathParameters` configuration option, which generates path parameters in the generated request type (if any) instead of as separate positional parameters.\
\
```yaml # generators.yml\
- name: fern-api/fern-go-sdk\
  version: 0.33.0\
  config:\
    inlinePathParameters: true\
```\
\
\
# November 20, 2024\
\
## 0.32.1\
\
**`(internal):`** Improve the aesthetics of the generated code, and reduce the amount of repetition in each of the generated endpoints. This change has zero impact on the behavior of the generated SDK.\
\
\
# November 18, 2024\
\
## 0.31.3\
\
**`(fix):`** Updates the retrier to stop retrying on `409 Conflict` HTTP status codes by default.\
\
\
# November 15, 2024\
\
## 0.31.1\
\
**`(internal):`** Adds additional tests to confirm the behavior of the `core.Retrier`.\
No functional, user-facing changes are included.\
\
\
# November 14, 2024\
\
## 0.31.0\
\
**`(feat):`** Improves type file layout with zero impact on backwards compatibility.\
Shared types are now more accurately placed in the `types.go` file, whereas types referenced by a single service are now placed in a file that matches the service's filename (e.g. user.go).\
\
\
# November 8, 2024\
\
## 0.29.0\
\
**`(feat):`** All SDKs now include an exported `FileParam` type that can be used to configure the `Content-Type` of file upload properties.\
\
**`(fix):`** Resolves an issue where multipart/form-data lists were incorrectly serialized as JSON. They are now added as individual parts.\
\
**`(internal):`** Refactor file upload endpoint generation with the new `core.MultipartWriter`. This significantly improves the aesthetics of the generated code.\
\
\
# November 7, 2024\
\
## 0.28.3\
\
**`(internal):`** Upgrade to IRv53.\
\
\
# November 6, 2024\
\
## 0.28.2\
\
**`(fix):`** Fix an issue where undiscriminated unions were not round-trippable whenever the union is the zero value of the type (e.g. `0` for `int`).\
\
\
# October 29, 2024\
\
## 0.28.1\
\
**`(fix):`** Fix an issue where optional, allow-multiple query parameter snippets were not rendered.\
\
**`(fix):`** Fix an issue where service headers were not included in the generated in-lined request.\
\
**`(fix):`** Fix an issue where literal types were included as path parameter arguments.\
\
\
# October 25, 2024\
\
## 0.28.0\
\
**`(feat):`** Add support for the exportedClientName configuration, which can be used to customize the generated client name and constructor included in snippets.\
Note that this configuration option assumes that the SDK includes a hand-written client constructor defined in the client package.\
\
\
# September 29, 2024\
\
## 0.27.0\
\
**`(feat):`** Add support for SSE (Server-Sent Events) streaming responses. The user-facing interface for streaming responses remains the same between standard HTTP streaming and SSE.\
\
\
# September 26, 2024\
\
## 0.26.0\
\
**`(feat):`** Add support for sending custom Content-Type header values defined in the API.\
\
\
# September 9, 2024\
\
## 0.25.0\
\
**`(feat):`** Add support for sending extra body properties and query parameters via `RequestOption`.\
\
\
# September 8, 2024\
\
## 0.24.0\
\
**`(feat):`** Add support for reading headers from environment variables (e.g. `X-API-Version`).\
\
\
# September 6, 2024\
\
## 0.23.7\
\
**`(fix):`** Fixes an issue where optional `unknown` values (typed as `interface\{\}`) were mistakenly dereferenced.\
\
\
# September 5, 2024\
\
## 0.23.5\
\
**`(fix):`** Fix an issue where `long` type examples (generated as `int64` in Go) were not successfully converted to their equivalent `string` representation for snippets.\
\
\
# August 30, 2024\
\
## 0.23.3\
\
**`(internal):`** No changes.\
\
\
# August 26, 2024\
\
## 0.23.2\
\
**`(internal):`** No changes.\
\
\
# August 19, 2024\
\
## 0.23.1\
\
**`(fix):`** Fix literal value deserialization.\
\
### What's changed\
\
* Updates object and undisriminated union deserialization to return an error whenever any literal values do not exist or are mismatched.\
\
\
# August 7, 2024\
\
## 0.23.0\
\
**`(feat):`** Add support for always sending required properties.\
\
### What's new\
\
* Added the `alwaysSendRequiredProperties` configuration option. When `alwaysSendRequiredProperties` is enabled, required properties are never omitted in the type's wire representation. Any required property that is not explicitly set will send the default value for that type.\
\
\
# July 22, 2024\
\
## 0.22.3\
\
**`(fix):`** Fix an issue where APIs that specify the `property-name` error discrimination strategy would receive JSON decode errors instead of the server's error.\
\
\
# July 4, 2024\
\
## 0.22.2\
\
**`(fix):`** Request types set to `nil` no longer send an explicit `null` value.\
\
\
# June 11, 2024\
\
## 0.22.1\
\
**`(fix):`** Array of `deepObject` query parameters are correctly serialized.\
\
\
# May 21, 2024\
\
## 0.22.0\
\
**`(feat):`** Add support for retrieving extra properties from response objects.\
\
### What's new\
\
* Extra properties decoded from response objects are retained and accessible via the `GetExtraProperties` method.\
\
\
# May 17, 2024\
\
## 0.21.3\
\
**`(internal):`** The generator now uses the latest FDR SDK.\
\
\
# May 7, 2024\
\
## 0.21.2\
\
**`(fix):`** In-lined request body properties no longer include a non-empty `url` struct tag.\
\
\
# April 29, 2024\
\
## 0.21.0\
\
**`(feat):`** Add support for cursor and offset pagination.\
\
\
# April 26, 2024\
\
## 0.20.2\
\
**`(internal):`** Enhance extra property serialization performance.\
\
**`(internal):`** Generate additional extra property tests into the SDK.\
\
**`(fix):`** Resolve a non-deterministic key ordering issue for snippets of type `unknown`.\
\
**`(fix):`** Resolve an issue with discriminated union serialization.\
\
\
# April 25, 2024\
\
## 0.20.1\
\
**`(fix):`** The `omitempty` struct tag is now only used for nil-able types.\
\
**`(fix):`** Update the query encoder to prevent unintentional errors whenever the `omitempty` is used for a non-optional field.\
\
\
# April 24, 2024\
\
## 0.20.0\
\
**`(feat):`** The Go generator now supports extra properties.\
\
\
# April 16, 2024\
\
## 0.19.0\
\
**`(feat):`** The Go generator now supports environment variable scanning.\
\
\
# April 15, 2024\
\
## 0.18.3\
\
**`(fix):`** Path parameters are now applied in the correct order.\
\
\
# April 2, 2024\
\
## 0.18.2\
\
**`(fix):`** Custom authorization header schemes had their values overridden by request options, which required using the generated request option at every call-site.\
\
\
# March 12, 2024\
\
## 0.18.1\
\
**`(fix):`** Go snippets correctly handle unknown examples.\
\
\
# March 4, 2024\
\
## 0.18.0\
\
**`(feat):`** Add support for simpler unions, which is configurable with `union: v1` (if omitted, the default `v0` version will be used).\
\
**`(feat):`** Add support for multiple files in upload endpoints.\
\
\
# February 26, 2024\
\
## 0.17.0\
\
**`(internal):`** No changes since previous release candidate.\
\
\
# February 23, 2024\
\
## 0.17.0-rc1\
\
**`(fix):`** Snippets for aliases to optional primitive values.\
\
\
# February 21, 2024\
\
## 0.17.0-rc0\
\
**`(fix):`** Package documentation is now generated into the correct package's `doc.go`.\
\
**`(feat):`** Add support for generated endpoint snippets.\
\
\
# February 12, 2024\
\
## 0.16.0\
\
**`(feat):`** The generator now supports whitelabelling.\
\
\
# February 9, 2024\
\
## 0.15.0\
\
**`(feat):`** Enforce RFC3339 for date\\[time] serialization in request bodies.\
\
\
# February 7, 2024\
\
## 0.14.1\
\
**`(fix):`** Query parameter support for optional `time.Time` types.\
\
\
# February 6, 2024\
\
## 0.14.0\
\
**`(feat):`** Add support for `deepObject` query parameters.\
\
**`(chore):`** Refactor query parameter serialization with `url` struct tags.\
\
\
# January 31, 2024\
\
## 0.12.1\
\
**`(fix):`** `text/plain` response handling.\
\
\
# January 30, 2024\
\
## 0.12.0\
\
**`(feat):`** Add support for `bytes` request bodies with `Content-Type` set to `application/octet-stream`.\
\
\
# January 29, 2024\
\
## 0.11.0\
\
**`(feat):`** Add automatic retry with exponential backoff.\
\
\
# January 25, 2024\
\
## 0.10.0\
\
**`(feat):`** Refactor `ClientOption` as `RequestOption`.\
\
**`(feat):`** Add `includeLegacyClientOptions` generator configuration.\
\
**`(feat):`** Support idempotency headers as a special `RequestOption` only available on idempotent endpoints.\
\
**`(fix):`** Placement of path parameter documentation.\
\
**`(fix):`** Naming collision issue for undiscriminated unions that define more than one literal.\
\
\
# January 10, 2024\
\
## 0.9.4\
\
**`(fix):`** File upload requests that specify query parameters.\
\
\
# December 4, 2023\
\
## 0.9.3\
\
**`(fix):`** Optional query parameter dereferencing issue.\
\
\
# November 30, 2023\
\
## 0.9.2\
\
**`(fix):`** Append version suffix for modules tagged with major versions greater than `1.X.X`.\
\
\
# November 8, 2023\
\
## 0.9.1\
\
**`(fix):`** Support boolean literals.\
\
**`(fix):`** Union subt-ypes with no properties are now go 1.13 compatible.\
\
\
# October 31, 2023\
\
## 0.9.0\
\
**`(feat):`** Add support for streaming endpoints.\
\
**`(feat):`** Add support for non-primitive file upload properties.\
\
**`(chore):`** Refactor `core.DoRequest` with `core.Caller` abstraction.\
\
**`(chore):`** Update pinned dependencies in generated `go.mod`.\
\
\
# November 25, 2024\
\
## 1.9.11\
\
**`(feat):`** Add two dependencies who previously were transitive dependencies to ensure the generated SDKs use the patched versions without vulnerabilities.\
\
* `System.Net.Http` >= `4.3.4`\
* `System.Text.RegularExpressions` >= `4.3.1`\
  Update other dependencies to the latest version:\
* `Portable.System.DateTimeOnly` = `8.0.2` (on net462 & netstandard2.0)\
* `PolySharp` = `1.15.0`\
* `OneOf` = `3.0.271`\
* `OneOf.Extended` = `3.0.271`\
\
\
# November 20, 2024\
\
## 1.9.10\
\
**`(feat):`** Add partial `JsonOptions.ConfigureJsonSerializerOptions` method to allow SDK maintainers to configure the `JsonSerializerOptions` used by the SDK.\
\
\
# November 19, 2024\
\
## 1.9.9\
\
**`(feat):`** Add support for [Auto Pagination](https://buildwithfern.com/learn/sdks/features/auto-pagination).\
When enabled, the endpoint methods will return a `Pager<T>` object that you can use to iterate over all items of an endpoint.\
Additionally, you can use the `Pager<T>.AsPagesAsync` method to iterate over all pages of an endpoint.\
The SDK will automatically make the necessary HTTP requests for you as you iterate over the items or the pages.\
\
\
# November 14, 2024\
\
## 1.9.8\
\
**`(feat):`** Add support for [idempotency headers](https://buildwithfern.com/learn/sdks/capabilities/idempotency-headers).\
\
\
# November 12, 2024\
\
## 1.9.7\
\
**`(feat):`** Set Content-Type header for HTTP requests when specified in the API spec/definition.\
\
\
# November 9, 2024\
\
## 1.9.5\
\
**`(feat):`** Copy the csproj Version as the AssemblyVersion and FileVersion.\
\
\
# November 8, 2024\
\
## 1.9.4\
\
**`(feat):`** Generate a ProjectName.Test.Custom.props file for you to configure any MSBuild properties for your test project.\
\
**`(feat):`** Only import ProjectName.Custom.props and ProjectName.Test.Custom.props if the file exists, so you can delete the file if you wish to.\
\
**`(fix):`** Do not re-import the .NET SDK inside of ProjectName.Custom.props.\
\
\
# November 7, 2024\
\
## 1.9.3\
\
**`(feat):`** Generate a ProjectName.Custom.props file for you to configure any MSBuild properties for your project.\
\
**`(fix):`** Generate the license NuGet properties inside the .csproj file correctly.\
\
\
# November 6, 2024\
\
## 1.9.1\
\
**`(chore):`** Update `System.Text.Json` dependency from `8.0.4` to `8.0.5` because a security patch was released to resolve [this vulnerability](https://github.com/advisories/GHSA-8g4q-xg66-9fp4).\
\
\
# November 5, 2024\
\
## 1.9.0\
\
**`(feat):`** Add support for calling HTTP endpoints and gRPC endoints within the same service.\
\
\
# October 30, 2024\
\
## 1.8.5\
\
**`(feat):`** Add forward-compatible enums. Set `experimental-enable-forward-compatible-enums` to `true` in the configuration to generate forward-compatible enums.\
With forward-compatible enums you can create and parse an enum value that is not predefined.\
\
* Forward compatible enums are not compatible with the previously generated native enums.\
  This is a breaking change for the users of the generated SDK, but only users using switch-case statements are affected.\
* Use the `Value` property to get the string value of the enum. - For each value in the enum,\
  * a public static property is generated, which is an instance of the enum class,\
  * a public static property is generated within the nested `Values` class with the string value of the enum.\
\
Here's a before and after for creating and parsing a resource with a predefined enum value and a custom enum value:\
**Before**:\
``csharp var resource = client.CreateResource(new Resource \{ Id = "2", EnumProperty = MyEnum.Value2 \} ); // The line below does not compile because the enum does not have a `Value3` value. // resource = client.CreateResource(new Resource \{ Id = "3", EnumProperty = MyEnum.Value3 \} ); resource = client.GetResource("3"); switch(resource.EnumProperty) \{\
    case MyEnum.Value1:\
        Console.WriteLine("Value1");\
        break;\
    case MyEnum.Value2:\
        Console.WriteLine("Value2");\
        break;\
    default:\
        // this will never be reached until the SDK is updated with the new enum value\
        Console.WriteLine("Unknown");\
        break;\
\} if(resource.EnumProperty == MyEnum.Value1) \{\
        Console.WriteLine("Value1");\
\} else if (resource.EnumProperty == MyEnum.Value2) \{\
        Console.WriteLine("Value2");\
\} else \{\
    // this will never be reached until the SDK is updated with the new enum value\
    Console.WriteLine("Unknown");\
\} ``\
No exception is thrown, but the output incorrectly shows `Value1` because .NET falls back to the first value in the enum.\
**After**:\
\
````csharp var resource = client.CreateResource(new Resource \{ Id = "2", EnumProperty = MyEnum.Value2 \} ); resource = client.CreateResource(new Resource \{ Id = "3", EnumProperty = MyEnum.Custom("value3") \} ); resource = client.GetResource("3"); switch(resource.EnumProperty.Value) \{\
    case MyEnum.Values.Value1:\
        Console.WriteLine("Value1");\
        break;\
    case MyEnum.Values.Value2:\
        Console.WriteLine("Value2");\
        break;\
    default:\
        Console.WriteLine(resource.EnumProperty.Value);\
        break;\
\} if(resource.EnumProperty == MyEnum.Value1) \{\
    Console.WriteLine("Value1");\
\} else if (resource.EnumProperty == MyEnum.Value2) \{\
    Console.WriteLine("Value2");\
\} else \{\
    Console.WriteLine(resource.EnumProperty.Value);\
\} ```\
The output correctly shows `Value3`.\
\
````\
\
\
# October 28, 2024\
\
## 1.8.2\
\
**`(fix):`** Fixes a bug where the ClientOptions would not compile due to incorrect Clone method generation.\
\
\
# October 8, 2024\
\
## 1.8.1\
\
**`(fix):`** Fixes a bug where the `OauthTokenProvider.cs` was incorrectly referencing\
the endpoint method, causing code to fail to compile.\
\
\
# August 29, 2024\
\
## 1.6.0\
\
**`(feat):`** Add support for generated `README.md` files.\
\
\
# August 28, 2024\
\
## 1.5.0\
\
**`(feat):`** Add support for service-level headers.\
\
**`(feat):`** Generate `snippet.json` file containing usage snippets for each endpoint.\
\
**`(feat):`** Apply the timeout configured on the `ClientOptions` and `RequestOptions` type.\
\
**`(feat):`** Add exponential backoff retrier, which acts upon `MaxRetries` configuration option specified on the `ClientOptions` and `RequestOptions`.\
\
**`(feat):`** Generate the `RawClientTests.cs` file which includes retry logic tests.\
\
**`(internal):`** Refactor the `RawClient` with additional helper methods so that it's easier to follow.\
\
**`(fix):`** Fix a bug where `OneOf` used directly as request or response types fail serialization.\
\
\
# August 26, 2024\
\
## 1.4.0\
\
**`(internal):`** Generate a `Version` class which is used to reference the current version.\
\
\
# August 22, 2024\
\
## 1.3.0-rc0\
\
**`(feat):`** Add support for sending the `User-Agent` header.\
\
**`(internal):`** The `RawClient` now supports HTTP headers within the `ClientOptions` and `RequestOptions` types.\
\
**`(feat):`** Add support for the `package-id` configuration, which is used to control the name of the package in NuGet.\
\
**`(feat):`** Add support for mock server tests with `generate-mock-server-tests` configuration option.\
\
**`(internal):`** Omit `null` property values in requests.\
\
**`(fix):`** Fix a bug where request bodies are not sent for wrapped requests that include headers or query params.\
\
**`(fix):`** Fix a bug where enums, dates, and datetimes are sometimes not serialized properly as query parameters and headers.\
\
**`(feat):`** Add support for `read-only-memory-types` configuration.\
\
**`(feat):`** Add the `CancellationToken` parameter as the last parameter to every endpoint method.\
\
**`(feat):`** Add support for gRPC/Protobuf endpoints.\
\
\
# August 12, 2024\
\
## 1.2.1\
\
**`(feat):`** Add support for Protobuf file dependencies to generate gRPC client stubs.\
\
**`(fix):`** Fix potential namespace and type conflicts.\
\
\
# August 11, 2024\
\
## 1.0.0\
\
**`(break):`** The C# SDK is now on major version 1.0.0. To preserve compatibility with pre-1.0.0, set all of \\\{root-namespace-for-core-classes, pascal-case-environments, simplify-object-dictionaries\} to `false`.\
\
**`(internal):`** Core classes that are exposed publicly are now in the root namespace.\
\
**`(internal):`** Types that were previously generated as `Dictionary<string, object?>` are now just `object`.\
\
**`(internal):`** Environment names are pascal-cased.\
\
**`(feat):`** Generating specific error types can now be turned off with the `generate-error-types` configuration.\
\
\
# August 10, 2024\
\
## 0.12.0\
\
**`(feat):`** Get better Unit Testing JSON comparison results by using `FluentAssertions`.\
\
\
# August 9, 2024\
\
## 0.11.0\
\
**`(internal):`** Mark internal files `internal`.\
\
**`(feat):`** Make all client classes `Partial`.\
\
**`(internal):`** Don't override `toString` on Exceptions.\
\
\
# August 7, 2024\
\
## 0.10.0\
\
**`(fix):`** Fix a bug where conflicting class names and namespaces cause compile to fail.\
\
\
# August 1, 2024\
\
## 0.9.0\
\
**`(feat):`** Add the `base-api-exception-class-name` and `base-exception-class-name` generator configuration. These control the class names of the generated `ApiException` and `Exception` class names.\
\
\
# July 31, 2024\
\
## 0.6.0\
\
**`(feat):`** Add support for `RequestOptions` allowing request-specific option overrides.\
\
\
# July 30, 2024\
\
## 0.3.3\
\
**`(internal):`** Generate types with `set` accessors instead of `init` to improve object construction flexibility.\
\
\
# July 29, 2024\
\
## 0.3.2\
\
**`(feat):`** The C# generator now supports configuration to match namespaces to file paths.\
\
\
# July 25, 2024\
\
## 0.2.0\
\
**`(break):`** Rename `Environments.cs` to `\{OrgName\}Environment`.\
\
**`(feat):`** Generate classes for environments with different endpoint URLs.\
\
\
# July 23, 2024\
\
## 0.1.4\
\
**`(internal):`** More improvements to datetime serialization.\
\
\
# July 22, 2024\
\
## 0.1.3\
\
**`(fix):`** Fixed a bug with serializing datetimes.\
\
**`(internal):`** Stop generating empty serialization unit test files when there are no examples.\
\
\
# July 17, 2024\
\
## 0.1.2\
\
**`(chore):`** Bump IR to 51.\
\
**`(feat):`** Generate serialization unit tests for models and add a GH workflow to run them.\
\
\
# July 10, 2024\
\
## 0.1.1\
\
**`(internal):`** Enable generating unions with up to 32 types by adding the OneOf.Extended package.\
\
**`(fix):`** Handle double optional fields properly with a single `?`.\
\
\
# July 9, 2024\
\
## 0.1.0\
\
**`(feat):`** Add targets for .NET Standard 2.0 and .NET Framework 4.6.2.\
\
**`(fix):`** Avoid duplicate key errors in `StringEnumSerializer`.\
\
**`(fix):`** Fix bugs with root client requests causing generation failures.\
\
**`(fix):`** Correctly handle environment values and literal header names.\
\
**`(internal):`** Improve constructor parameters and other minor fixes.\
\
\
# July 2, 2024\
\
## 0.0.34\
\
**`(fix):`** Implement base client methods instead of leaving them empty.\
\
\
# June 21, 2024\
\
## 0.0.31\
\
**`(fix):`** Ensure the HTTP client joins endpoint path with the base URL safely.\
\
\
# June 20, 2024\
\
## 0.0.25\
\
**`(feat):`** Discriminated unions are now generated as object.\
\
**`(feat):`** Header parameters are no longer required in the constructor, eliminating the need for users to provide redundant information.\
\
\
# June 19, 2024\
\
## 0.0.24\
\
**`(fix):`** Query and header parameters are now ISO 8601 encoded before making requests.\
\
\
# June 7, 2024\
\
## 0.0.22\
\
**`(feat):`** The SDK now includes support for .NET 4.\
\
\
# May 31, 2024\
\
## 0.0.21\
\
**`(fix):`** Array and list fields are now generated as `IEnumerable`.\
\
\
# May 29, 2024\
\
## 0.0.19\
\
**`(fix):`** Enum serializers now handle reading and writing enum string values.\
\
**`(fix):`** Non-success status code errors are now thrown with the stringified response body.\
\
\
# May 28, 2024\
\
## 0.0.17\
\
**`(feat):`** Enabled nullable on all C# files.\
\
**`(feat):`** Made project compatible with .NET 6, .NET 7, and .NET 8.\
\
\
# May 23, 2024\
\
## 0.0.14\
\
**`(feat):`** The SDK now includes a `JsonEnumMemberStringEnumConverter`.\
\
\
# May 22, 2024\
\
## 0.0.12\
\
**`(feat):`** The C# generator now generates an `Environments.cs` file containing URLs for different environments.\
\
\
# May 20, 2024\
\
## 0.0.11\
\
**`(feat):`** The C# generator now generates a proper `.csproj` file with version, GitHub URL, and a reference to the SDK README.\
\
\
# May 15, 2024\
\
## 0.0.10\
\
**`(feat):`** The generated SDK now publishes GitHub Actions to build and publish the generated package to NuGet.\
\
\
# May 10, 2024\
\
## 0.0.8\
\
**`(fix):`** Several bug fixes.\
\
### What's new\
\
* Support for arbitrary nested clients\
* Query parameter serialization\
\
### What's changed\
\
* Property naming for async methods\
* Properly formatted solution files\
\
\
# December 11, 2024\
\
## 2.7.0\
\
**`(feat):`** Apply Content-Type header from endpoint definition in SDK generator.\
\
\
# December 10, 2024\
\
## 2.4.0\
\
**`(feat):`** We now support overriding sdk package prefixes by adding a "package-prefix" key under the java-sdk generator\
configuration.\
\
\
# December 4, 2024\
\
## 2.3.0\
\
**`(feat):`** Fix publishing to Maven Central with proper signing configuration and metadata.\
\
\
# September 26, 2024\
\
## 2.2.0\
\
**`(feat):`** We now provide endpoint methods for streaming byte array requests in addition to the previous methods accepting\
byte array directly.\
\
**`(chore):`** Bump Jackson version to latest (2.17.2)\
\
\
# September 11, 2024\
\
## 2.1.0\
\
**`(feat):`** We no longer enforce non-null constraints for Object type properties in builders.\
\
\
# September 5, 2024\
\
## 2.0.0\
\
**`(break):`** The SDK generator is now on major version 2. To take this upgrade without any breaks, please add the below\
configuration to your `generators.yml` file:\
\
```yaml\
generators:\
  - name: fernapi/fern-java-sdk\
    config:\
      disable-required-property-builder-checks: true\
```\
\
**`(feat):`** Generated builder methods now enforce non-null checks for required fields, ensuring that all required\
fields are properly validated during object construction:\
\
```java\
@java.lang.Override\
@JsonSetter("name")\
public NameStage name(@NotNull String name) \{\
    this.name = Objects.requireNonNull(name, "name must not be null");\
    return this;\
\}\
```\
\
\
# September 4, 2024\
\
## 1.0.6\
\
**`(fix):`** Fixed a bug where optional collections are not handled properly in paginated responses.\
\
\
# July 26, 2024\
\
## 1.0.5\
\
**`(fix):`** Fixed a bug where local generation custom config doesn't pick up some values, including exception naming.\
\
\
# July 24, 2024\
\
## 1.0.4\
\
**`(fix):`** Fixed a bug where OkHttp responses could be closed prematurely.\
\
\
# July 23, 2024\
\
## 1.0.3\
\
**`(feat):`** Generated builder methods for optional fields can now accept null directly.\
\
\
# July 2, 2024\
\
## 1.0.2-rc0\
\
**`(feat):`** The generator now adds a class-level `@JsonInclude(JsonInclude.Include.NON_ABSENT)` annotation to\
each generated type in place of the previous `@JsonInclude(JsonInclude.Include.NON_EMPTY)` by default. This is\
configurable in the `generators.yml` file:\
\
```yaml\
generators:\
  - name: fernapi/fern-java-sdk\
    config:\
      json-include: non-empty # default non-absent\
```\
\
\
# June 26, 2024\
\
## 1.0.1\
\
**`(break):`** The Java SDK is now on major version 1. To take this upgrade without any breaks, please add the below\
configuration to your `generators.yml` file:\
\
```yaml\
generators:\
  - name: fernapi/fern-java-sdk\
    config:\
      base-api-exception-class-name: ApiError\
      base-exception-class-name: CompanyException # Optional: This should only be set if default naming is undesirable\
```\
\
**`(feat):`** We now generate Exception types for all errors that are defined in the IR. Generated clients with an\
error discrimination strategy of "status code" will throw one of these typed Exceptions based on the status code of\
error responses. Example error type:\
\
```java\
public final class BadRequest extends MyCompanyApiError \{\
  public BadRequest(Object body) \{\
      super("BadRequest", 400, body);\
  \}\
\}\
```\
\
\
# June 13, 2024\
\
## 0.10.1\
\
**`(feat):`** Add support for cursor and offset pagination.\
\
### What's new\
\
* Add support for cursor and offset pagination.\
\
For example, consider the following endpoint `/users` endpoint:\
\
```yaml\
types:\
  User:\
    properties:\
      name: string\
\
  ListUserResponse:\
    properties:\
      next: optional<string>\
      data: list<User>\
\
service:\
  auth: false\
  base-path: /users\
  endpoints:\
    list:\
      path: ""\
      method: GET\
      pagination:\
        cursor: $request.starting_after\
        next_cursor: $response.next\
        results: $response.data\
      request:\
        name: ListUsersRequest\
        query-parameters:\
          starting_after: optional<string>\
      response: ListUsersResponse\
```\
\
The generated `SyncPagingIterable<User>` can then be used to traverse through the `User` objects:\
\
```java\
for (User user : client.users.list(...)) \{\
    System.out.println(user);\
\}\
```\
\
Or stream them:\
\
```java\
client.users.list(...).streamItems().map(user -> ...);\
```\
\
Or statically calling `nextPage()` to perform the pagination manually:\
\
```java\
SyncPagingIterable<User> pager = client.users.list(...);\
// First page\
System.out.println(pager.getItems());\
// Second page\
pager = pager.nextPage();\
System.out.println(pager.getItems());\
```\
\
\
# June 7, 2024\
\
## 0.10.0\
\
**`(feat):`** The generator now supports BigInteger types.\
\
\
# June 6, 2024\
\
## 0.9.7\
\
**`(feat):`** The SDK generator now generates `@java.lang.Override` over `@Override` in all files to avoid clashes with any\
`Override.java` class that may have been generated in the same package. The former was used most places, but not all,\
until this release.\
\
\
# June 5, 2024\
\
## 0.9.6\
\
**`(feat):`** The SDK generator now supports returning response properties from client methods rather than just the responses themselves.\
\
\
# May 30, 2024\
\
## 0.9.4\
\
**`(fix):`** The SDK now generates undiscriminated unions with de-conflicted method signatures. Previously, certain undiscriminated unions would have failed to compile due to Java's type erasure causing conflicts.\
\
\
# May 23, 2024\
\
## 0.9.3\
\
**`(feat):`** Generated SDK clients with an OAuth security scheme will now automatically refresh access tokens before they expire.\
\
\
# May 21, 2024\
\
## 0.9.2\
\
**`(fix):`** Java 8 Compatibility.\
\
\
# May 15, 2024\
\
## 0.9.1\
\
**`(fix):`** Support OAuth without token refresh. Example of initializing a client with OAuth:\
\
```java\
ExampleApiClient client = ExampleApiClient\
    .builder()\
    .clientId("4bf2a37d-8512-44a2-af50-28a7701d9f2e")\
    .clientSecret("b3b187b0-ef48-49ba-9d99-80d89fd11c4a")\
    .build();\
```\
\
\
# May 13, 2024\
\
## 0.9.0-rc0\
\
**`(internal):`** Bump intermediate representation to v42\
\
\
# May 8, 2024\
\
## 0.8.10\
\
**`(fix):`** Fixes regression from 0.8.8, headers are no longer added to the header map unless they are non-null.\
\
\
# May 7, 2024\
\
## 0.8.8\
\
**`(fix):`** The generated SDKs no longer require global headers that are not directly related to auth if auth is mandatory within the SDK. Previously, the generator would require all global headers if auth was mandatory.\
\
\
# March 21, 2024\
\
## 0.8.7\
\
**`(feat):`** You can now specify publishing metadata to populate your POM on publish:\
\
```yaml\
generators:\
  - name: fernapi/fern-java-sdk\
    version: 0.X.Y\
    output:\
      location: maven\
      registryUrl: ""\
      publish-metadata:\
        author: ""\
        email: ""\
        package-description: ""\
        reference-url: ""\
```\
\
\
# March 20, 2024\
\
## 0.8.6\
\
**`(fix):`** The SDK now generates RequestOptions functions for timeouts with IdempotentRequestOptions correctly, previously\
timeout functions were only taking in regular RequestOptions. This also addresses a JavaPoet issue where fields were\
being initialized twice across RequestOptions and IdempotentRequestOptions classes, preventing the SDK from generating at all.\
\
\
# March 18, 2024\
\
## 0.8.5\
\
**`(feat):`** Add in publishing config that allows for signing published artifacts, this is required for publishing to Maven\
Central.\
To sign your artifacts, you must add the below to your publishing config:\
\
```yaml\
generators:\
  - name: fernapi/fern-java-sdk\
    version: 0.X.Y\
    output:\
      location: maven\
      registryUrl: ""\
      signature:\
        keyId: ""\
        password: ""\
        secretKey: ""\
```\
\
and secrets can be used, similar to how API keys are specified today:\
\
```yaml\
generators:\
  - name: fernapi/fern-java-sdk\
    version: 0.X.Y\
    output:\
      location: maven\
      registryUrl: ""\
      signature:\
        keyId: $\{MY_KID_ENVVAR\}\
        password: $\{MY_SECRET_ENVVAR\}\
        secretKey: $\{MY_SECRET_KEY_ENVVAR\}\
```\
\
\
# February 23, 2024\
\
## 0.8.3\
\
**`(fix):`** The SDK generator now always creates a valid name for union discriminator wrapper classes.\
\
\
# February 21, 2024\
\
## 0.8.2\
\
**`(fix):`** File upload endpoints no longer fail to compile because the reference to\
the mime type variable is present.\
\
```java\
// Code that failed to compile\
String fileMimeType = Files.probeContentType(file.toPath());\
MediaType fileMediaType = fileMimeType != null ? MediaType.parse(mimeType) : null; // mimeType undefined\
// Code that now compiles\
MediaType fileMediaType = fileMimeType != null ? MediaType.parse(fileMimeType) : null;\
```\
\
\
# February 14, 2024\
\
## 0.8.1\
\
**`(feat):`** The RequestOptions object now supports configuring an optional timeout to apply per-request.\
\
```java\
RequestOptions ro = RequestOptions.builder().timeout(90).build(); // Creates a timeout of 90 seconds for the request\
//  You could also specify the timeunit, similar to as if you were using OkHttp directly\
//  RequestOptions ro = RequestOptions.builder().timeout(2, TimeUnit.MINUTES).build();\
client.films.list(ro);\
```\
\
\
# February 11, 2024\
\
## 0.8.0\
\
**`(feat):`** The SDK generator now supports whitelabelling. When this is turned on,\
there will be no mention of Fern in the generated code.\
\
**Note**: You must be on the enterprise tier to enable this mode.\
\
\
# February 4, 2024\
\
## 0.7.1\
\
**`(feat):`** The SDK generator now supports idempotency headers. Users\
will be able to specify the idempotency headers in RequestOptions.\
\
```java\
Imdb imdb = Imdb.builder()\
  .apiKey("...")\
  .build();\
\
var response = imdb.ticket.purchase("theatre-id", IdempotentRequestOptions.builder()\
  .idempotencyKey("...")\
  .build());\
```\
\
**`(feat):`** The SDK generator now supports scanning API credentials\
via environment varaibles.\
\
```java\
Imdb imdb = Imdb.builder()\
  .apiKey("...") // defaults to System.getenv("IMDB_API_KEY")\
  .build();\
```\
\
**`(feat):`** The generated models now support boolean literals and users\
do not have to specify them in the builder.\
For example, for the following object\
\
```yaml\
Actor:\
  properties:\
    name: string\
    isMale: literal<true>\
```\
\
the user will not need to specify the literal properties when building\
the object.\
\
```java\
var actor = Actor.builder()\
  .name("Brad Pitt")\
  .build();\
```\
\
\
# February 3, 2024\
\
## 0.6.1\
\
**`(internal):`** Release version 0.6.1\
\
\
# November 20, 2024\
\
## 0.2.1\
\
**`(fix):`** Override escaped method names in the generated client.\
\
\
# October 30, 2024\
\
## 0.2.0\
\
**`(feat):`** Add support for multipart file uploads.\
\
\
# October 3, 2024\
\
## 0.1.3\
\
**`(feat):`** Support inheritance for types and inlined requests.\
\
**`(feat):`** Support undiscriminated unions.\
\
**`(fix):`** Fix ci.yml `php-version` field name.\
\
**`(feat):`** We now allow an empty constructor on types with no required properties.\
\
\
# September 25, 2024\
\
## 0.1.2\
\
**`(feat):`** Represent enums in objects as strings.\
\
**`(fix):`** Generated wrapped requests now implement `JsonSerializableType`.\
\
**`(fix):`** Fix a bug where we don't set the request options baseurl properly.\
\
**`(fix):`** Fix bugs in our numeric type serde and add tests.\
\
\
# September 24, 2024\
\
## 0.1.0\
\
**`(feat):`** Initial release.\
\
\
# August 5, 2024\
\
## 0.8.2\
\
**`(fix):`** The generated endpoint functions no long include object utilities such as `_field_set` or `additional_properties`.\
\
\
# July 22, 2024\
\
## 0.8.1\
\
**`(fix):`** Address serialization issues within iterable types\
\
### What's been fixed\
\
* Nested `hash` types are recursively resolved in `from_json` such that they come back as true hashes, as opposed to structs\
* Pass through additional params from request options even if the original request did not have those types of params (ex: query parameters)\
\
\
# July 3, 2024\
\
## 0.8.0\
\
**`(fix):`** Date snippets now wrap their examples in quotation marks to correctly use `.parse`\
\
\
# July 1, 2024\
\
## 0.8.0-rc0\
\
**`(feat):`** allow users to specify additional dependencies and dev dependencies for Ruby SDKs.\
\
\
# June 13, 2024\
\
## 0.7.0-rc0\
\
**`(feat):`** Introduce automatic token refresh for OAuth credentials\
\
### What's new\
\
* The Ruby SDK now generates an OAuth client to automate token refresh.\
\
### What's been fixed\
\
* The Ruby SDK now no longer requires users specify literals in method signatures\
\
\
# May 27, 2024\
\
## 0.6.3\
\
**`(feat):`** Generated SDK snippets now leverage the full function module path.\
\
\
# May 17, 2024\
\
## 0.6.2\
\
**`(internal):`** The generator now uses the latest FDR SDK\
\
\
# April 9, 2024\
\
## 0.5.0-rc0\
\
**`(feat):`** The generated SDK now includes a rakefile to run any tests prefixed with `test_` in the `test` directory\
\
### What's new\
\
* Consumers of the SDK can now pass in a base URL override into the root client, as well as the request's RequestOptions\
\
### What's been fixed\
\
* This PR includes a number of typing annotation and cleanliness/QOL fixes.\
\
\
# April 8, 2024\
\
## 0.4.0\
\
**`(feat):`** The generated SDK now includes a rakefile to run any tests prefixed with `test_` in the `test` directory\
\
### What's new\
\
* The generators now create a rakefile to run any tests prefixed with `test_` in the `test` directory. A step is also added to CI to run these test. The dummy test now running also provides a sanity check on the health of the build of the gem, even if no tests are added given the gem is imported.\
\
\
# March 22, 2024\
\
## 0.0.2\
\
**`(feat):`** Support rubygems output type within `generators.yml`\
\
\
# March 18, 2024\
\
## 0.3.2\
\
**`(feat):`** type bytes requests to also take in IO types, indicating to users that they may pass in a stream of bytes\
\
\
# March 12, 2024\
\
## 0.3.1\
\
**`(fix):`** use strings instead of UUIDs, which are helper classes in Ruby\
\
\
# February 27, 2024\
\
## 0.3.0\
\
**`(fix):`** Generated yardoc now appropriately reflects the typehint of the value type in maps\
\
### What's been fixed\
\
* Ensure the name passed into the 'X-Fern-SDK-Name' header is the name of the gem, not the client class\
* If an envvar is specified as a fallback for an auth header, the SDK will now mark that parameter as optional to allow fallback to actually happen\
* Generated yardoc now appropriately reflects the typehint of the value type in maps\
\
\
# February 20, 2024\
\
## 0.2.0\
\
**`(feat):`** Add support for idempotency headers\
\
### What's changed\
\
* Ruby enum construct now leverages class constants instead of hashes to support better autocomplete\
* Discriminated unions are no longer wrapped within a parent object, rather, any field or parameter that depends on a discriminated union now explicitly references the member types in support of better autocomplete.\
* Undiscriminated unions are no longer allowed as hashes as input to SDK functions, this is in support of better autocomplete as well.\
* The generated Ruby SDKs now support idempotency headers, users may specify idempotency headers within the RequestOptions object\
\
\
# February 15, 2024\
\
## 0.1.1\
\
**`(internal):`** Ensure the Ruby generators do not have strict dependencies on the IR\
\
\
# February 1, 2024\
\
## 0.0.1\
\
**`(feat):`** Support client generation (async and sync) as well as most endpoint types (except streaming)\
\
\
# January 30, 2024\
\
## 0.0.0\
\
**`(internal):`** Initialize the changelog\
\
\
# Strongly Typed\
\
> Move fast and break nothing with type safety\
\
Fern generated SDKs are optimized for great autocompletion in\
code editors. Developers will receive compile errors when they forget to\
specify required fields or attempt to access fields that do not exist.\
\
<Tabs>\
  <Tab title="TypeScript">\
    TypeScript SDKs are published with type declarations (i.e. `.d.ts` files). This\
    ensures that TypeScript consumers can leverage compile-time safety and\
    intellisense when using the SDK.\
\
    Each SDK method is annotated with request and response types.\
\
    ```typescript maxLines=0 \{10\}\
    import \{ Genre \} from "../genre";\
\
    export interface MovieClient \{\
\
      /**\
       * Creates a movie\
       * @param request the movie to create\
       * @returns the created Movie\
       */\
      void create(request: CreateMovieRequest): Promise<Movie>; \
    \}\
\
    export interface CreateMovieRequest \{\
      name: string;\
      genre: Genre; \
    \}\
\
    export interface Movie \{\
      /* Generated ID for the movie */\
      id: string;\
      name: string;\
      genre: Genre; \
    \}\
    ```\
  </Tab>\
</Tabs>\
\
\
# Idiomatic Method Names\
\
> Fine-tune SDK resources and method names\
\
Fern allows you to fine-tune your SDK method and group names so that\
your SDK reads exactly how you want it to. For example, instead of\
`client.postUsers` you can configure the SDK to read `client.users.create()`.\
\
<CodeBlocks>\
  <CodeBlock title="TypeScript">\
    ```ts\
    const response = await client.users.create();\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Python">\
    ```python\
    response = client.users.create()\
    # or async \
    response = await async_client.users.create()\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Java">\
    ```java\
    const response = client.users().create();\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Go">\
    ```go\
    const response = client.Users.Create();\
    ```\
  </CodeBlock>\
</CodeBlocks>\
\
Groups can also be arbitrarily nested. For example, if you want to nest the `users`\
endpoints under an `admin` group, the SDK would then read:\
\
<CodeBlocks>\
  <CodeBlock title="TypeScript">\
    ```ts\
    const response = await client.admin.users.create();\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Python">\
    ```python\
    response = client.admin.users.create()\
    # or async \
    response = await async_client.amdin.users.create()\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Java">\
    ```java\
    const response = client.admin().users().create();\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Go">\
    ```go\
    const response = client.Admin.Users.Create();\
    ```\
  </CodeBlock>\
</CodeBlocks>\
\
<Note>\
  See how merge.dev uses nested groups [here](https://github.com/merge-api/merge-node-client?tab=readme-ov-file#create-link-token).\
</Note>\
\
If you're using an OpenAPI Specification, you'll need to leverage the [`x-fern-sdk-method-name`](/learn/api-definition/openapi/extensions#sdk-method-names)\
extension. If you're using the fern definition, then the method name comes from the endpoint directly.\
\
## Casing\
\
Additionally, Fern handles choosing the appropriate casing for each SDK\
language: `snake_case` in python, `camelCase` in TypeScript and `PascalCase` in Go, etc.\
\
\
# Schema validation\
\
> Fail-fast if the payloads diverge from your schema\
\
Often times, your API Definition may drift from your server implementation.\
If you are concerned about this, you can toggle on schema validation in the\
SDKs.\
\
It's worth nothing that this feature is **optional** for duck-typed\
languages like Python, TypeScript, and Ruby. However, for strongly typed\
languages like Go, Java, and C# this is always on.\
\
<Tabs>\
  <Tab title="TypeScript">\
    The TypeScript SDK contains a `serialization` folder when generated.\
\
    ```\{5\}\
    src/\
      api/\
      core/\
      errors/\
      serialization/\
      Client.ts\
      index.ts\
    ```\
\
    Inside of this serialization folder, are [zod](https://github.com/colinhacks/zod)-like schemas for every\
    generated model.\
\
    For example, if you had a `Movie` schema defined in your API Definition and\
    wanted to validate the schema, you could simply do:\
\
    ```ts\
    import \{ Movie \} from "@my-company/sdk";\
    import * as serializers from "@my-company/sdk/serialization";\
\
    const movie: Movie = \{\
      name: "GoodwillHunting";\
    \}\
    // serialize \
    serializers.Movie.jsonOrThrow(movie);\
    // deserialize\
    serializers.Movie.parseOrThrow("\{ \\"name\\": \\"Goodwill Hunting\\" \}");\
    ```\
\
    Fern allows you to generate the SDK in three different modes:\
\
    1. **No validation**: In this mode, there is no serialization layer generated. Types exist at\
       compile time, but they are completely removed at runtime.\
    2. **Request validation only**: In this mode, the serialization layer is only used to\
       validate requests. Responses are always returned even if they do not match the schema. This is\
       the recommended mode for public API companies.\
    3. **Full validation**: In this mode, the serialization layer is used to validate both\
       requests and responses. This is the recommended mode for internal SDKs so that you can catch\
       issues as soon as possible.\
  </Tab>\
</Tabs>\
\
\
# Discriminated Unions\
\
> Fern SDKs include idiomatic support for discriminated unions\
\
The SDKs natively support [discriminated unions](../../api-definition/fern/types#discriminated-unions) for both OpenAPI and Fern APIs.\
\
<AccordionGroup>\
  <Accordion title="Fern Definition">\
    Discriminated unions are defined with the `union` key. For example, a simple\
    `Shape` type that can either be a `Triangle` or a `Square` can be defined as follows:\
\
    <CodeBlock title="fern/definition/shape.yml">\
      ```yaml\
      types:\
        Shape:\
        union:\
          triangle: Triangle\
          square: Square\
\
      Triangle:\
        properties:\
          a: double\
          b: double\
          c: double\
\
      Square:\
        properties:\
          side: double\
      ```\
    </CodeBlock>\
\
    With this, the JSON representation for a `Shape` looks like the following:\
\
    <CodeBlock title="triangle.json">\
      ```json\
      \{\
        "type": "triangle",\
        "a": 3,\
        "b": 4,\
        "c": 5\
      \}\
      ```\
    </CodeBlock>\
\
    or\
\
    <CodeBlock title="square.json">\
      ```json\
      \{\
        "type": "square",\
        "side": 5\
      \}\
      ```\
    </CodeBlock>\
  </Accordion>\
\
  <Accordion title="OpenAPI Specification">\
    Discriminated unions are defined with the `oneOf` and `anyOf` keys. For example, consider\
    the following `Shape` definition:\
\
    <CodeBlock title="openapi.yml">\
      ```yaml\
      components:\
        schemas:\
          Shape:\
            oneOf:\
              - $ref: "#/components/schemas/Triangle"\
              - $ref: "#/components/schemas/Square"\
          Triangle:\
            type: object\
            properties:\
              type:\
                type: string\
                enum:\
                  - triangle\
              a:\
                type: number\
              b:\
                type: number\
              c:\
                type: number\
            required:\
              - type\
              - a\
              - b\
              - c\
          Square:\
            type: object\
            properties:\
              type:\
                type: string\
                enum:\
                  - square\
              side:\
                type: number\
            required:\
              - type\
              - side\
      ```\
    </CodeBlock>\
\
    With this, the JSON representation for a `Shape` looks like the following:\
\
    <CodeBlock title="triangle.json">\
      ```json\
      \{\
        "type": "triangle",\
        "a": 3,\
        "b": 4,\
        "c": 5\
      \}\
      ```\
    </CodeBlock>\
\
    or\
\
    <CodeBlock title="square.json">\
      ```json\
      \{\
        "type": "square",\
        "side": 5\
      \}\
      ```\
    </CodeBlock>\
  </Accordion>\
</AccordionGroup>\
\
<Tabs>\
  <Tab title="TypeScript">\
    ```ts maxLines=0 \{1\}\
    export type Shape = Triangle | Square;\
\
    export interface Triangle \{\
      type: "triangle";\
      a: number;\
      b: number;\
      c: number;\
    \}\
\
    export interface Square \{\
      type: "square";\
      side: number;\
    \}\
    ```\
\
    Callers can create a `Shape` object by simply constructing the appropriate type. For example, creating\
    a `Triangle` shape looks like the following:\
\
    ```ts\
    const shape: Shape = \{\
      type: "triangle",\
      a: 3,\
      b: 4,\
      c: 5,\
    \};\
    ```\
\
    Consumers can easily write branching logic by checking the discriminant.\
\
    ```ts \{4, 6\}\
    import \{ Shape \} from "sdk";\
\
    export function computeArea(shape: Shape): number \{\
      if (shape.type === "triangle") \{\
        // compute triangle area\
      \} else if (shape.type === "square") \{\
        // compute square area\
      \}\
    \}\
    ```\
  </Tab>\
\
  <Tab title="Go">\
    Go does not have a built-in support for discriminated unions. However, you can define a union struct\
    to achieve the same effect:\
\
    ```go maxLines=0 \{1-5\}\
    type Shape struct \{\
    	Type     string\
    	Triangle *Triangle\
    	Square   *Square\
    \}\
\
    type Triangle struct \{\
    	A float64 `json:"a" url:"a"`\
    	B float64 `json:"b" url:"b"`\
    	C float64 `json:"c" url:"c"`\
    \}\
\
    type Square struct \{\
    	Side float64 `json:"side" url:"side"`\
    \}\
    ```\
\
    Callers can create a `Shape` object by simply setting the appropriate key. For example, creating\
    a `Triangle` shape looks like the following:\
\
    ```go\
    shape := &Shape\{\
      // You do not need to set the Type field manually, the SDK will automatically set it for you.\
      Triangle: &Triangle\{\
        A: 3,\
        B: 4,\
        C: 5,\
      \},\
    \}\
    ```\
\
    Consumers can easily write a `switch` statement by checking the discriminant:\
\
    ```go \{3, 5\}\
    func ComputeArea(shape *Shape) float64 \{\
      switch shape.Type \{\
      case "triangle":\
        // compute triangle area\
      case "square":\
        // compute square areair\
      \}\
    \}\
    ```\
  </Tab>\
</Tabs>\
\
\
# Multipart Form Data\
\
> SDKs that handle multipart form data\
\
Fern generated SDKs natively support uploading files and other media through\
multipart form data uploads.\
\
<Tabs>\
  <Tab title="TypeScript">\
    The TypeScript SDK will accept either a `fs.readStream`, `fs.ReadableStream` or a\
    `Blob` for the file types. This is to ensure that the file upload functionality\
    can be used in the browser, Node.js and edge runtimes like Next.js and Cloudflare.\
\
    This is what the SDK method signature would look like:\
\
    ```ts DocumentClient.ts\
    export interface DocumentClient \{\
      \
      /**\
       * Upload a document.\
       */\
      public async upload(\
          contents: fs.ReadStream | fs.ReadableStream | Blob,\
          request: UploadDocumentBodyRequest,\
          requestOptions?: RequestOptions\
      ): Promise<UploadDocumentResponse>  \
    \}\
    ```\
\
    and how a user would consume it\
\
    ```ts\
    await client.documents.upload(fs.createReadStream('/path/to/your/file.txt'), \{\
      label: 'Human-friendly label for your document',\
    \});\
    ```\
  </Tab>\
</Tabs>\
\
\
# Forward compatibility\
\
> SDKs that are fault-tolerant as your API evolves\
\
Fern SDKs are designed so that you can evolve your API without breaking users on\
legacy SDKs. You can safely add additional response properties, enum values, and union variants.\
The legacy SDKs will safely handle deserializing extra information.\
\
<Tabs>\
  <Tab title="TypeScript">\
    ### Additional Response Properties\
\
    As you make new response properties available,\
    the legacy SDKs will continue to work. For example, let's say you\
    generated an SDK that had the following `Movie` object:\
\
    ```ts\
    export interface Movie \{\
      name: string;\
      id: string;\
    \}\
    ```\
\
    If you decided to add a new `genre` property on your server, the SDK will\
    simply pass the extra property back. Users would also be able to access\
    the property by doing\
\
    ```ts\
    const genre = movie['genre'];\
    ```\
\
    ### Additional Enum values\
\
    As you add additional enum properties on your server, the\
    legacy SDKs will continue to work. For example, let's say your generated SDK\
    had the following `Genre` type:\
\
    ```ts\
    export type Genre =\
      | "horror"\
      | "action"\
      | "thriller"\
      | "drama";\
    ```\
\
    If you decided to add a new enum value `comedy`, the SDK will simply pass\
    the string value back to the user. The consumer can then handle this case\
    in the default case of a switch statement.\
\
    ```ts \{6-7\}\
    switch(genre) \{\
      case "horror": \
      case "action": \
      case "thriller": \
      case "drama": \
      default: \
        console.log(genre); // prints out comedy\
    \}\
    ```\
\
    ### Additional union variants\
\
    Similar to additional enum properties, if you add additional union types\
    on your server, the legacy SDKs will continue to work. For example, let's say your\
    generated SDK had the following `Shape` type:\
\
    ```ts\
    export type Shape = Square | Circle;\
\
    export interface Circle \{\
      type: "circle",\
      radius: number\
    \}\
\
    export interface Square \{\
      type: "square",\
      side: number\
    \}\
    ```\
\
    If you decided to add an additional union type called `Triangle`\
\
    ```ts\
    + export type Shape = Square | Circle | Triangle;\
\
    + export interface Triangle \{\
    +   type: "triangle",\
    +   a: number\
    +   b: number\
    +   c: number\
    + \}\
    ```\
\
    then the user could simply handle the unknown case in their legacy SDK.\
\
    ```ts \{6-7\}\
    switch (type) \{\
      case "circle": \
        ...\
      case "square": \
        ...\
      default: \
        console.log(type); // prints out triangle\
    \}\
    ```\
  </Tab>\
</Tabs>\
\
\
# Automated publishing to registries\
\
> Fern will automatically publish your SDKs to registries like NPM, PyPI, and Maven\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
Fern will automatically publish your SDKs to registries like NPM, PyPI, and Maven. This means\
that you can easily distribute your SDKs to your users without having to worry\
about the publishing process.\
\
<Steps>\
  ### Configure your output location\
\
  In your `generators.yml` you can specify which generators (e.g. Python, Go, TypeScript) you\
  would like to subscribe to. To publish to a registry, you will need to specify the `output`\
  location for the SDK.\
\
  <CodeBlocks>\
    <CodeBlock title="TypeScript">\
      ```yaml \{7-10\}\
        groups: \
          ts-sdk: \
            - name: fernapi/fern-typescript-node-sdk\
              version: 0.13.0\
              config: \
                namespaceExport: Imdb\
              output: \
                location: npm\
                package-name: "@imdb/sdk"\
                token: $\{ NPM_TOKEN \} # must be present in the environment\
      ```\
    </CodeBlock>\
\
    <CodeBlock title="Python">\
      ```yaml \{7-10\}\
        groups: \
          python-sdk: \
            - name: fernapi/fern-python-sdk\
              version: 1.0.0\
              config: \
                client_class_name: Imdb\
              output: \
                location: pypi\
                package-name: "imdb"\
                token: $\{ PYPI_TOKEN \} # must be present in the environment\
      ```\
    </CodeBlock>\
\
    <CodeBlock title="Java">\
      ```yaml \{7-10\}\
        groups: \
          java-sdk: \
            - name: fernapi/fern-java-sdk\
              version: 0.12.0\
              config: \
                client-class-name: Imdb\
              output: \
                location: maven\
                username: $\{ MAVEN_USERNAME \} # must be present in the environment\
                password: $\{ MAVEN_PASSWORD \} # must be present in the environment\
                coordinate: com.imdb:imdb-java\
      ```\
    </CodeBlock>\
  </CodeBlocks>\
\
  ### Run `fern generate`\
\
  Once you have configured your `generators.yml`, you can run `fern generate` to\
  trigger the SDK generation process.\
\
  <Note>\
    To control the version of your package specify the `--version` flag. For example,\
    `fern generate --version 1.0.0` would publish version `1.0.0`.\
  </Note>\
</Steps>\
\
### Private registries\
\
In some cases, you may want to publish your SDKs to a private registry. Fern hosts\
private registries for you at `npm.buildwithfern.com`, `pypi.buildwithfern.com`,\
`maven.buildwithfern.com`, etc. To use an internal registry, simply specify the\
`url` field in your `generators.yml`:\
\
<Warning>\
  If you are using a private registry, then your package name must have `fern` postfixed to it.\
  For example, `@imdb-fern/sdk`, `imdb-fern`, and `com.imdb.fern:imdb-java`.\
</Warning>\
\
<CodeBlocks>\
  <CodeBlock title="TypeScript">\
    ```yaml \{8\}\
      groups: \
        ts-sdk: \
          - name: fernapi/fern-typescript-node-sdk\
            version: 0.13.0\
            config: \
              namespaceExport: Imdb\
            output: \
              url: npm.buildwithfern.com\
              location: npm\
              package-name: "@imdb-fern/sdk"\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Python">\
    ```yaml \{8\}\
      groups: \
        ts-sdk: \
          - name: fernapi/fern-python-sdk\
            version: 1.0.0\
            config: \
              client_class_name: Imdb\
            output: \
              url: pypi.buildwithfern.com\
              location: pypi\
              package-name: "imdb-fern"\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Java">\
    ```yaml \{8\}\
      groups: \
        ts-sdk: \
          - name: fernapi/fern-java-sdk\
            version: 0.12.0\
            config: \
              client-class-name: Imdb\
            output: \
              url: maven.buildwithfern.com\
              location: maven\
              coordinate: com.imdb.fern:imdb-java\
    ```\
  </CodeBlock>\
</CodeBlocks>\
\
<Note>\
  To use a private registry, you will need to set the `FERN_TOKEN` environment variable.\
</Note>\
\
\
# Auto Pagination\
\
> Paginate through API responses easily with offset, cursor, and link-based pagination.\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. [Contact us](https://buildwithfern.com/contact) to get started.\
</Warning>\
\
Instead of forcing SDK users to learn the intricacies of your pagination system, Fern SDKs will return an iterator so that users can simply loop through all the results.\
\
<Tabs>\
  <Tab title="TypeScript">\
    When pagination for an endpoint is configured, the TypeScript SDK method\
    will return a `Page<T>` where `T` is the underlying data type. The `Page<T>`\
    will implement the `AsyncIterable` interface, allowing you to use it in a\
    `for await` loop.\
\
    Below is an example method signature for a list endpoint:\
\
    ```typescript UsersClient.ts \{10-13\}\
    import core from "../core";\
\
    export interface UsersClient \{\
\
      /**\
       * List all users\
       * @param props \
       * @returns A page of users\
       */\
      list(\
        request: ListUsersRequest = \{\}, \
        requestOptions: core.RequestOptions = \{\}\
      ): core.Page<User>;\
    \}\
    ```\
\
    And here is an example of how a user would use the `list` method:\
\
    ```typescript\
    const response = await client.users.list();\
    for await (const user of response) \{\
      console.log(user);\
    \}\
    ```\
  </Tab>\
\
  <Tab title="Python">\
    When pagination for an endpoint is configured, the Python SDK method\
    will return a `Pager[T]` (specifically a `SyncPager[T]` or an `AsyncPager[T]`) where `T` is the underlying data type. The `Pager[T]`\
    will implement the `Generator` interface, allowing you to use it in a\
    `for ... in` loop.\
\
    Below is an example method signature for a list endpoint:\
\
    ```python client.py \{3-9\}\
    class UsersClient:\
\
      def list_with_cursor_pagination(\
          self,\
          *,\
          page: typing.Optional[int] = None,\
          page_size: typing.Optional[int] = None,\
          request_options: typing.Optional[RequestOptions] = None,\
      ) -> SyncPager[User]:\
        ...\
    ```\
\
    And here is an example of how a user would use the `list` method:\
\
    ```python\
    for user in client.users.list(page=1, page_size=10):\
      print(user)\
    ```\
\
    or if the user is leveraging the asynchronous client:\
\
    ```python\
    async for user in await client.users.list(page=1, page_size=10):\
      print(user)\
    ```\
  </Tab>\
</Tabs>\
\
### Supported pagination types\
\
Fern supports the following pagination schemes:\
\
| Pagination Scheme | Supported                             |\
| ----------------- | ------------------------------------- |\
| Offset-based      | <Icon icon="check" color="#84B060" /> |\
| Cursor-based      | <Icon icon="check" color="#84B060" /> |\
| Link-based        |                                       |\
\
#### Configuration\
\
Annotate the desired paginated endpoint with the `x-fern-pagination` extension.\
For these fields, you can simply specify the dot-access path to the related request or response property.\
\
For example, should the results of the following object be found in the subfield `inner_list`, you would specify `results: $response.my_nested_object.inner_list`.\
\
```yaml\
MyResponseObject:\
  type: object\
  properties:\
    my_nested_object:\
      type: object\
      properties:\
        inner_list:\
          type: array\
          items:\
            $ref: '#/components/schemas/MyObject'\
```\
\
<Tabs>\
  <Tab title="OpenAPI">\
    <CodeBlocks>\
      ```yaml Offset\
      ...\
      paths:\
        /path/to/my/endpoint:\
          x-fern-pagination:\
            offset: $request.page_number\
            results: $response.results\
      ...\
      ```\
\
      ```yaml Cursor\
      ...\
      paths:\
        /path/to/my/endpoint:\
          x-fern-pagination:\
            cursor: $request.cursor\
            next_cursor: $response.next\
            results: $response.results\
      ...\
      ```\
    </CodeBlocks>\
  </Tab>\
\
  <Tab title="Fern Definition">\
    <CodeBlocks>\
      ```yaml Offset\
      service:\
        endpoints:\
          listWithOffsetPagination:\
            pagination: \
              offset: $request.page\
              results: $response.data\
      ```\
\
      ```yaml Cursor\
      service:\
        endpoints:\
          listWithCursorPagination:\
            pagination: \
              cursor: $request.starting_after\
              next_cursor: $response.page.next.starting_after\
              results: $response.data\
      ```\
    </CodeBlocks>\
  </Tab>\
</Tabs>\
\
\
# OAuth\
\
> Fern supports OAuth as a first class citizen\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
Fern supports the OAuth 2.0 authorization framework as a first class citizen. With Fern, users don't need\
to retrieve and manage access tokens manually. Instead, Fern SDKs will handle the entire OAuth flow.\
\
For the `client-credentials` OAuth flow, the user simply provides their `client-id` and `client-secret`,\
and they're ready to go.\
\
<Tabs>\
  <Tab title="TypeScript">\
    When OAuth is configured, the TypeScript SDK's client constructor will include the `clientId` and\
    `clientSecret` parameters.\
\
    Constructing the client is as simple as:\
\
    ```typescript Client.ts\
    client = new Client(\{\
      clientId: 'YOUR_CLIENT_ID',\
      clientSecret: 'YOUR_CLIENT_SECRET',\
    \});\
    ```\
\
    Behind the scenes, the `core.OAuthTokenProvider` retrieves an access token and refreshes it as needed. With this,\
    the rest of the API (like the `User` client) can use the token to authenticate every request.\
  </Tab>\
\
  <Tab title="Python">\
    When OAuth is configured, the Python SDK's client constructor will include the `client_id` and\
    `client_secret` parameters.\
\
    Constructing the client is as simple as:\
\
    ```python client.py\
    client = Client(\
      client_id="YOUR_CLIENT_ID",\
      client_secret="YOUR_CLIENT_SECRET",\
    )\
    ```\
\
    Behind the scenes, the `core.OAuthTokenProvider` retrieves an access token and refreshes it as needed. With this,\
    the rest of the API (like the `UserClient`) can use the token to authenticate every request.\
  </Tab>\
\
  <Tab title="Java">\
    When OAuth is configured, the Java SDK\'92s builder methods for setting the `clientId` and `clientSecret` are available.\
\
    Constructing the client is as simple as:\
\
    ```java client.java\
    Client client = Client.builder()\
        .clientId("YOUR_CLIENT_ID")\
        .clientSecret("YOUR_CLIENT_SECRET")\
        .build();\
    ```\
\
    Behind the scenes, the `core.OAuthTokenProvider` retrieves an access token and refreshes it as needed. With this,\
    the rest of the API (like the `UserClient`) can use the token to authenticate every request.\
  </Tab>\
</Tabs>\
\
### Supported authorization flows\
\
Fern supports the following OAuth authorization flows:\
\
| Authorization Flow | Supported                             | Example                                                     |\
| ------------------ | ------------------------------------- | ----------------------------------------------------------- |\
| client-credentials | <Icon icon="check" color="#84B060" /> | [Sayari](https://github.com/sayari-analytics/sayari-python) |\
| authorization-code | <Icon icon="check" color="#84B060" /> | [Webflow](https://github.com/webflow/webflow-python)        |\
| pkce               |                                       |                                                             |\
\
\
# Retries with Backoff\
\
> Automatically retry failures with exponential backoff\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
Fern SDKs will automatically retry failed requests with exponential backoff. A request will be retried as\
long as the request is deemed retriable and the number of retry attempts has\
not grown larger than the configured retry limit.\
\
### Retriable status codes\
\
A request is deemed retriable when any of the following HTTP status codes is returned:\
\
* [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)\
* [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)\
* [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)\
\
Note that you can configure the list of retriable status codes as well. For example,\
if you want to remove the `429` status code from the list of retriable status codes, you can do so.\
\
### Overriding the retry limit\
\
By default, the SDK will retry a failed request up to 2 times. SDK users can override the global\
default retry limit when instantiating the client.\
\
<CodeBlocks>\
  <CodeBlock title="TypeScript">\
    ```ts \{4\}\
    import \{ ImdbClient \} from "imdb";\
\
    const client = new ImdbClient(\{\
      maxRetries: 1 // overrides the default retry limit to 1\
    \});\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Python">\
    ```python \{4, 8\}\
    from imdb.client import Imdb, AsyncImdb\
\
    client = Imdb(\{\
      max_retries: 1 # overrides the default retry limit to 1\
    \})\
\
    async_client = AsyncImdb(\{\
      max_retries: 1 # overrides the default retry limit to 1\
    \})\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Java">\
    ```java \{4\}\
    import com.imdb.ImdbClient;\
\
    ImdbClient client = new ImdbClient.Builder()\
      .maxRetries(1) // overrides the default retry limit to 1\
      .build();\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Go">\
    ```go \{7\}\
      import (\
        imdbclient "github.com/fern-workos/workos-go/client"\
        "github.com/fern-workos/workos-go/option"\
      )\
\
      client := imdbclient.NewClient(\
        option.WithMaxAttempts(1), // overrides the default retry limit to 1\
      )\
    ```\
  </CodeBlock>\
</CodeBlocks>\
\
It's also possible to override the retry limit on a per-request basis.\
\
<CodeBlocks>\
  <CodeBlock title="TypeScript">\
    ```ts \{2\}\
      client.movie.get("tt0111161", \{\
        maxRetries: 3 // overrides the default retry limit to 3\
      \});\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Python">\
    ```python \{2\}\
      client.movie.get("tt0111161", \{\
        max_retries: 3 // overrides the default retry limit to 3\
      \})\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Java">\
    ```java \{2\}\
      client.movie().get("tt0111161", RequestOptions.builder()\
        .maxRetries(3) // overrides the default retry limit to 3\
        .build());\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Go">\
    ```go \{4\}\
      response, err := client.Movies.Get(\
        ctx,\
        "tt0111161",\
        option.WithMaxAttempts(1),\
      )\
    ```\
  </CodeBlock>\
</CodeBlocks>\
\
\
# Webhook Signature Verification\
\
> Verify the signature of incoming webhook requests\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
Fern's SDKs export helper function to verify the signature of incoming webhook requests.\
There are three benefits to using this feature:\
\
1. **Security**: Users can ensure that the incoming webhook request is from your server.\
2. **Ease of Use**: Instead of making consumers write signature verification logic, you can use the SDK's helper function.\
3. **Strongly Typed**: The SDK will parse the incoming payload and return a strongly typed object.\
\
Each SDK exports a `constructEvent` function that takes in the incoming payload and the signature. The\
function will return a strongly typed object that represents the incoming webhook event.\
\
<CodeBlocks>\
  <CodeBlock title="TypeScript">\
    ```ts\
    const payload = client.webhooks.constructEvent(\{\
      body: req.body,\
      signature: req.headers['x-imdb-signature'],\
      secret: process.env.WEBHOOK_SECRET\
    \})\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Python">\
    ```python\
    payload = client.webhooks.construct_event(\
      body=request.text(),\
      signature=request.headers['x-signature'],\
      secret=os.environ['WEBHOOK_SECRET']\
    )\
    ```\
  </CodeBlock>\
</CodeBlocks>\
\
\
# Idempotency Headers\
\
> SDKs that safely support retrying requests\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
For any idempotent endpoints, Fern's SDKs will allow you to specify idempotency headers.\
Typically the headers include `Idempotency-Key`, but you can also specify additional headers.\
\
<CodeBlocks>\
  <CodeBlock title="TypeScript">\
    ```ts \{5\}\
    const response = await client.transactions.send(\{\
      amount: 100,\
      currency: "usd",\
    \}, \{\
      idempotencyKey: "64099353-b48b-4dcd-98b7-74df1cc57933"\
    \});\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Python">\
    ```python \{4\}\
    response = client.transactions.send(\
      amount=100, \
      currency="USD", \{\
      idempotency_key="64099353-b48b-4dcd-98b7-74df1cc57933"\
    \})\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Java">\
    ```java \{7\}\
    var response = client.transactions().send(\
      SendTransactionsRequest.builder()\
        .amount(100)\
        .currency(Currency.USD)\
        .build(),\
      IdempotentRequestOptions.builder()\
        .idempotencyKey("64099353-b48b-4dcd-98b7-74df1cc57933")\
        .build()\
    );\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Go">\
    ```go \{7\}\
    response, err := client.Transactions.Send(\
      ctx,\
      &SendTransactionsRequest\{\
        Amount: 100,\
        Currency: Currency.USD,\
      \},\
      option.WithIdempotencyKey("64099353-b48b-4dcd-98b7-74df1cc57933"),\
    )\
    ```\
  </CodeBlock>\
</CodeBlocks>\
\
Note that the generated SDKs will not allow you to specify idempotency headers\
for non-idempotent endpoints. This is to ensure that the user knows exactly\
which invocations are idempotent and which are not.\
\
\
# Server-Sent Events\
\
> Stream JSON data from your server to your client (i.e. chat completions)\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
Fern's SDKs support Server-Sent Events (SSE) out of the box. This feature is\
especially relevant for chat completions, where you want to stream LLM\
outputs in real-time.\
\
<Tabs>\
  <Tab title="TypeScript">\
    When an endpoint is configured to use Server-Sent Events, the TypeScript SDK\
    method will return an `AsyncIterable` of the underlying data type. This\
    allows you to use it in a `for await` loop.\
\
    Below is an example method signature for a stream endpoint:\
\
    ```ts ChatClient.ts \{10-13\}\
    import core from "../core";\
\
    export interface ChatClient \{\
\
      /**\
      * Stream chat completions\
      * @param props \
      * @returns An async iterable of chat completions\
      */\
      stream(\
        request: ChatStreamRequest, \
        requestOptions: core.RequestOptions = \{\}\
      ): AsyncIterable<ChatCompletion>;\
    \}\
    ```\
\
    And here is an example of how a user would use the `stream` method:\
\
    ```ts\
    const response = await client.chat.stream(\{\
      query: "What is the weather in New York?"\
    \});\
    for await (const completion of response) \{\
      console.log(completion);\
    \}\
    ```\
  </Tab>\
\
  <Tab title="Python">\
    When an endpoint is configured to use Server-Sent Events, the Python SDK\
    method will return an `typing.Iterator` of the underlying data type.\
\
    Below is an example method signature for a chat endpoint:\
\
    ```py chat_client.py \{5-10\}\
    from fern import core\
\
    class ChatClient:\
\
      def stream(\
        self, \
        *, \
        query: str,\
        request_options: typing.Optional[RequestOptions]\
      ) -> typing.Iterator[StreamedChatResponse]:\
        pass\
    ```\
\
    And here is an example of how a user would use the `stream` method:\
\
    ```py\
    response = client.chat.stream(\
      query = "What is the weather in New York?",\
    )\
    for completion in response:\
      print(completion)\
    ```\
\
    ### Async client\
\
    The Python SDK will also export an asynchronous version of the client. The async client\
    will return an `AsyncIterator` instead of a regular iterator.\
\
    ```py chat_client.py \{5-10\}\
    from fern import core\
\
    class ChatClient:\
\
      def stream(\
        self, \
        *, \
        query: str,\
        request_options: typing.Optional[RequestOptions]\
      ) -> typing.AsyncIterator[StreamedChatResponse]:\
        pass\
    ```\
\
    And here is an example of how a user would use the async `stream` method:\
\
    ```py\
    import asyncio\
\
    async def main(): \
      response = await client.chat.stream(\
        query = "What is the weather in New York?",\
      )\
      async for completion in response:\
        print(completion)\
\
    asyncio.run(main())\
    ```\
  </Tab>\
</Tabs>\
\
\
# Integration Tests\
\
> Test your SDK against a mock server\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
To make sure that your SDK works in production, Fern will auto-generate\
integration tests that run before release. The release will only take place\
if no tests fail.\
\
### What gets generated?\
\
<AccordionGroup>\
  <Accordion title="Mock Server">\
    Fern will use your API Definition to generate a mock server that will be used\
    in the integration tests. The mock server will assert that the SDK is\
    making the correct requests.\
\
    By default, the mock server will use the examples specified in your\
    API Definition. If no examples are specified, Fern will generate examples to\
    the best of its ability.\
\
    <Note>\
      Specifying examples in your API Definition is recommended to ensure so that you can\
      control what data is used in the tests.\
    </Note>\
  </Accordion>\
\
  <Accordion title="Integration Tests">\
    Fern will generate integration tests as part of your SDK. These integration tests\
    will run against the mock server and assert validity of requests and responses.\
\
    The generated tests will use appropriate testing framework for the language:\
\
    * Jest for JavaScript/TypeScript\
    * Pytest for Python\
    * JUnit for Java\
    * RSpec for Ruby\
    * NUnit for C#\
    * The standard library for Go\
  </Accordion>\
\
  <Accordion title="GitHub Wofklows">\
    Fern will generate a GitHub workflow that will run the integration tests\
    on every pull request, commit and release.\
\
    <Frame caption="The `test` job runs the integration tests">\
      ![GitHub Workflow](https://fern-image-hosting.s3.amazonaws.com/fern/test-ci.png)\
    </Frame>\
  </Accordion>\
</AccordionGroup>\
\
### Adding additional tests\
\
If you would like to add additional tests, you can do so by committing them\
directly to the generated SDK repositories. Note that you will need to\
add the test files to your `.fernignore` file to prevent them from being\
overwritten by Fern.\
\
<Tabs>\
  <Tab title="TypeScript">\
    <Steps>\
      ### Create `tests/custom.test.ts`\
\
      ```typescript\
        import \{ MyClient \} from '../src';\
\
        describe('MyClient', () => \{\
          it('should do something', async () => \{\
            const client = new MyClient();\
            const response = await client.resource.get();\
            expect(response).toEqual(\{ something: 'something' \});\
          \});\
        \});\
      ```\
\
      ### Run your test\
\
      ```bash\
      yarn install\
      yarn test tests/custom.test.ts\
      ```\
\
      ### `.fernignore` your test file\
\
      ```yaml .fernignore \{3\}\
      # Specify any files that shouldn't be modified by Fern\
\
      tests/custom.test.ts\
      ```\
    </Steps>\
  </Tab>\
\
  <Tab title="Python">\
    <Steps>\
      ### Create `tests/test_custom.py`\
\
      ```python\
          from package.client import MyClient\
\
          def test() -> None:\
              client = MyClient()\
              response = client.resource.get()\
              assert response.something === "something"\
      ```\
\
      ### Run your test\
\
      ```bash\
      poetry install\
      poetry run pytest tests/test_custom.py -rP\
      ```\
\
      ### `.fernignore` your test file\
\
      ```yaml .fernignore \{3\}\
        # Specify any files that shouldn't be modified by Fern\
        \
      tests/test_custom.py\
      ```\
    </Steps>\
  </Tab>\
\
  <Tab title="Java">\
    <Steps>\
      ### Create `src/test/java/com/example/MyClientTest.java`\
\
      ```java\
      package com.example;\
\
      import static org.junit.jupiter.api.Assertions.assertEquals;\
      import org.junit.jupiter.api.Test;\
      import com.example.MyClient;\
\
      public class MyClientTest \{\
\
        @Test\
        public void testSomething() \{\
          MyClient client = new MyClient();\
          var response = client.getResource().get();\
          assertEquals("something", response.getSomething());\
        \}\
\
      \}\
      ```\
\
      ### Run your test\
\
      ```bash\
      ./gradlew test --tests com.example.MyClientTest\
      ```\
\
      ### `.fernignore` your test file\
\
      ```yaml .fernignore \{3\}\
      # Specify any files that shouldn't be modified by Fern\
\
      src/test/java/com/example/MyClientTest.java\
      ```\
    </Steps>\
  </Tab>\
</Tabs>\
\
\
# Code Snippets\
\
> No longer depend on manually written code snippets\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
Fern generates code snippets of how to consume the SDK in various languages.\
These code snippets are embedded in a variety of different locations:\
\
### Snippets in the SDK\
\
Each SDK contains code snippets so that users can see usage examples\
on hover. See examples below:\
\
<CodeBlocks>\
  <CodeBlock title="TypeScript">\
    ```typescript focus=\{6-11\} maxLines=0\
    export interface MovieClient \{\
      /**\
       * Create a new movie\
       * @param request: a request to create a movie\
       * \
       * @example\
       * const response = await client.movie.create(\{\
       *  title: 'Inception',\
       *  year: 2010,\
       *  director: 'Christopher Nolan'\
       * \});\
       */\
      create(request: CreateMovieRequest): Promise<CreateMovieResponse>; \
    \}\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Python">\
    ```python focus=\{18-25\} maxLines=0\
    class MovieClient:\
\
      def create(\
        self, \
        *,\
        title: str,\
        year: int,\
        director: str\
      ) -> CreateMovieResponse: \
          """\
          Create a new movie\
          \
          Parameters: \
            - title: str. The title of the movie.\
            - year: int. The year the movie was released.\
            - director: str. The director of the movie.\
          ---\
          from imdb.client import Imdb\
          \
          client = Imdb()\
          response = client.movie.create(\
            title='Inception',\
            year=2010,\
            director='Christopher Nolan'\
          )\
          """\
    ```\
  </CodeBlock>\
</CodeBlocks>\
\
### Snippets in documentation\
\
If you use Fern to generate your developer documentation, then you can configure the code\
snippets to be automatically populated in your documentation.\
\
<Frame caption="Automatically populated code snippets">\
  ![Code snippets](https://fern-image-hosting.s3.amazonaws.com/fern/sdk-code-snippets-in-docs.png)\
</Frame>\
\
### Snippets over API\
\
We also provide a public API that you can use to [fetch code snippets](/learn/cli-api/api-reference/snippets/get). This is useful if you\
want to display code snippets in your own documentation or website.\
\
<Frame caption="merge.dev uses the snippets API to populate their documentation">\
  ![Code snippets](https://fern-image-hosting.s3.amazonaws.com/fern/merge-code-snippets.png)\
</Frame>\
\
\
# Augment with custom code\
\
> Extend the generated SDK to provide additional functionality\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
The Fern generated SDKs are designed to be extended with custom code. Your custom code\
can be used to add additional functionality to the SDK and will live in harmony with\
the generated code.\
\
## Custom logic\
\
If you want to provide any logic in your SDK that goes beyond hitting the REST API, you can\
do so by leveraging `.fernignore`.\
\
Simply add your custom files to the SDK repository and  list them out in `.fernignore`. Fern\
won't override any files that you add in `.fernignore`.\
\
<Tabs>\
  <Tab title="TypeScript">\
    <Steps>\
      ### Create a new file `src/helper.ts`\
\
      ```typescript\
      export function myHelper(): void \{\
        return console.log("Hello world!");\
      \}\
      ```\
\
      ### Add `src/helper.ts` to `.fernignore`\
\
      <CodeBlock title=".fernignore">\
        ```yaml \{3\}\
        # Specify files that shouldn't be modified by Fern\
\
        src/helper.ts\
        ```\
      </CodeBlock>\
\
      ### Consume the helper\
\
      Now your users can consume the helper function by importing it from the SDK:\
\
      ```typescript\
      import \{ myHelper \} from "sdk/helper";\
\
      myHelper();\
      ```\
    </Steps>\
  </Tab>\
\
  <Tab title="Python">\
    <Steps>\
      ### Create a new file `src/<package>/helper.py`\
\
      ```python\
      def my_helper() -> None: \
        print "Hello World!"\
      ```\
\
      ### Add `src/<package>/helper.py` to `.fernignore`\
\
      <CodeBlock title=".fernignore">\
        ```yaml \{3\}\
        # Specify files that shouldn't be modified by Fern\
\
        src/<package>/helper.py\
        ```\
      </CodeBlock>\
\
      ### Consume the helper\
\
      Now your users can consume the helper function by importing it from the SDK:\
\
      ```python\
      from package.helper import my_helper\
\
      my_helper()\
      ```\
    </Steps>\
  </Tab>\
\
  <Tab title="Java">\
    <Steps>\
      ### Create a new file `src/main/java/<package>/Helper.java`\
\
      ```java\
      package com.example.helper;\
\
      public class Helper \{\
\
        public static void myHelper() \{\
          System.out.println("Hello World!");\
        \}\
\
      \}\
      ```\
\
      ### Add `src/main/java/<package>/Helper.java` to `.fernignore`\
\
      <CodeBlock title=".fernignore">\
        ```yaml \{3\}\
        # Specify files that shouldn't be modified by Fern\
\
        src/main/java/<package>/Helper.java\
        ```\
      </CodeBlock>\
\
      ### Consume the helper\
\
      Now your users can consume the helper function by importing it from the SDK:\
\
      ```java\
      import com.example.helper.Helper;\
\
      public class Main \{\
\
        public static void main(String[] args) \{\
          Helper.myHelper();\
        \}\
\
      \}\
      ```\
    </Steps>\
  </Tab>\
\
  <Tab title="Go">\
    <Steps>\
      ### Create a new file `helper.go`\
\
      ```go\
      func MyHelper() \{\
        fmt.Println("Hello World!")\
      \}\
      ```\
\
      ### Add `helper.go` to `.fernignore`\
\
      <CodeBlock title=".fernignore">\
        ```yaml \{3\}\
        # Specify files that shouldn't be modified by Fern\
\
        helper.go\
        ```\
      </CodeBlock>\
\
      ### Consume the helper\
\
      Now your users can consume the helper function by importing it from the SDK:\
\
      ```go\
      import "github.com/package/example"\
\
      example.MyHelper();\
      ```\
    </Steps>\
  </Tab>\
</Tabs>\
\
## Custom SDK methods\
\
Fern also allows you to add custom methods to the SDK itself (e.g. `client.my_method()` ).\
\
While the specifics are slightly different for each language, the underlying\
principle is the same: **extension**. You can inherit the\
Fern generated client and add whatever methods you want.\
\
<Tabs>\
  <Tab title="TypeScript">\
    <Note>\
      See an example from Flatfile using this process in their [TypeScript SDK](https://github.com/FlatFilers/flatfile-node)\
    </Note>\
\
    <Steps>\
      ### Create a new file `src/wrapper/MyClient.ts`\
\
      You can import the Fern generated client from `../client` and alias it to `FernClient`.\
      Next, extend `FernClient` and add whatever methods you want.\
\
      ```typescript\
      import \{ MyClient as FernClient \} from "../client"; // alias the Fern generated client\
\
      export class MyClient extends FernClient \{ // extend the Fern generated client\
        \
        public myHelper(): void \{\
          console.log("Hello world!");\
        \}\
\
      \}\
      ```\
\
      ### Export the extended client\
\
      Instead of exporting the generated client, export the extended client. To do this,\
      you will need to update the `index.ts` file.\
\
      <CodeBlock title="src/index.ts">\
        ```typescript\
        export \{ MyClient \} from src/wrapper/MyClient; // instead of `src/Client`\
        ```\
      </CodeBlock>\
\
      ### Update `.fernignore`\
\
      Add both the `wrapper` directory and `index.ts` to `.fernignore`.\
\
      <CodeBlock title=".fernignore">\
        ```diff\
        + src/wrapper\
        + src/index.ts\
        ```\
      </CodeBlock>\
\
      ### Consume the method\
\
      Now your users can consume the helper function by importing it from the SDK:\
\
      ```typescript\
      client.myHelper()\
      ```\
    </Steps>\
  </Tab>\
\
  <Tab title="Python">\
    <Note>\
      See an example from ElevenLabs using this process in their [Python SDK](https://github.com/elevenlabs/elevenlabs-python/blob/main/src/elevenlabs/client.py).\
    </Note>\
\
    <Steps>\
      ### Update `generators.yml` configuration\
\
      To add a custom method to the Python SDK, you will need to configure the\
      generator to output the client in a file called `base_client.py`. Then, you can\
      extend the base client and add whatever methods you want. See the\
\
      ```yaml \{4-8\}\
      - name: fernapi/fern-python-sdk\
        version: "..."\
        config:\
          client:\
            class_name: BaseClient        # The name of the generated client you will extend\
            filename: base_client.py      # The name of the file the generated client will live in\
            exported_class_name: Client   # The name of the class you will be creating that extends the generated client\
            exported_filename: client.py \
      ```\
\
      ### Generate the SDK\
\
      Trigger SDK generation by running `fern generate`.\
\
      ### Create a new file `src/<package>/client.py`\
\
      You can import the Fern generated client from `../client` and alias it to `FernClient`.\
      Next, extend `FernClient` and add whatever methods you want.\
\
      ```python\
      from .base_client import \\\
        BaseClient, AsyncBaseClient\
\
      class YourClient(BaseClient): \
\
        def my_helper(): -> None\
          print("Hello World")\
\
      class AsyncYourClient(AsyncBaseClient): \
\
        def my_helper(): -> None\
          print("Hello World")\
\
      ```\
\
      ### Update `.fernignore`\
\
      Add the `client.py` to `.fernignore`.\
\
      <CodeBlock title=".fernignore">\
        ```diff\
        + src/<package>/client.py\
        ```\
      </CodeBlock>\
\
      ### Consume the method\
\
      Now your users can consume the helper function by importing it from the SDK:\
\
      ```typescript\
      client.my_helper()\
      ```\
    </Steps>\
  </Tab>\
\
  <Tab title="Java">\
    <Steps>\
      ### Rename the Fern-generated client\
\
      We suggest naming your Fern-generated client something like `BaseClient`to reflect that this client will be extended.\
\
      ```yml \{4\}\
      - name: fernapi/fern-java-sdk\
          version: "..."\
          config:\
            client-class-name: BaseClient \
      ```\
\
      ### Create a new file `src/main/java/com/example/MyClient.java`\
\
      You can extend the Fern client and add whatever methods you want.\
\
      ```java\
      package com.example;\
\
      import com.example.client.BaseClient;\
\
      public class MyClient extends BaseClient \{ // extend the Fern generated client\
\
        public void myHelper() \{\
          System.out.println("Hello World!");\
        \}\
\
      \}\
      ```\
\
      ### Update `.fernignore`\
\
      Add the `MyClient.java` to `.fernignore`.\
\
      <CodeBlock title=".fernignore">\
        ```diff\
        + src/main/java/com/example/MyClient.java\
        ```\
      </CodeBlock>\
\
      ### Consume the method\
\
      ```java\
      client.myHelper();\
      ```\
    </Steps>\
  </Tab>\
\
  <Tab title="Go">\
    <Steps>\
      ### Create a new file `client/my_client.go`\
\
      You can import the Fern generated client from the same package and add whatever methods you want.\
\
      ```go\
      type MyClient struct \{\
        *Client // Embed the Fern generated client.\
      \}\
\
      func NewMyClient(opts ...option.RequestOption) *MyClient \{\
        retun &MyClient\{\
          Client: NewClient(opts...),\
        \}\
      \}\
\
      func (m *MyClient) MyHelper() \{\
        fmt.Println("Hello World!")\
      \}\
      ```\
\
      ### Export the extended client\
\
      Instead of constructing the generated client, your users will want to construct the extended client.\
\
      <CodeBlock title="main.go">\
        ```go\
        import exampleclient "github.com/package/example/client"\
\
        client := exampleclient.NewMyClient():\
        ```\
      </CodeBlock>\
\
      ### Update `.fernignore`\
\
      Add the \\`client/my\\_client.go.\
\
      <CodeBlock title=".fernignore">\
        ```diff\
        + client/my_client.go\
        ```\
      </CodeBlock>\
\
      ### Consume the method\
\
      Now your users can consume the helper function by importing it from the SDK:\
\
      ```go\
      client.MyHelper()\
      ```\
    </Steps>\
  </Tab>\
</Tabs>\
\
## Custom dependencies\
\
To add custom dependencies to your generated SDKs, you can update your `generators.yml`.\
\
<CodeBlocks>\
  <CodeBlock title="TypeScript">\
    ```yaml \{4-7\}\
    - name: fernapi/fern-typescript-node-sdk\
      version: "..."\
      config:\
        extraDependencies: \
          lodash-es: '1.0.0'\
        extraDevDependencies: \
          "@types/lodash-es": '1.0.0'\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="Python">\
    ```yaml \{4-7\}\
    - name: fernapi/fern-python-sdk\
      version: "..."\
      config:\
        extra_dependencies: \
          numpy: '1.2.0'\
        extra_dev_dependencies: \
          requests_mock: '1.12.1'\
    ```\
  </CodeBlock>\
</CodeBlocks>\
\
\
# Merging multiple API specs\
\
> Multiple API Definitions. One SDK.\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
Fern supports intelligently merging multiple API Definitions into a single SDK. This feature\
is useful when you have multiple micro-services that you would like to expose as a single\
SDK.\
\
<AccordionGroup>\
  <Accordion title="Single API">\
    You can specify your API Definition in `generators.yml`. In the normal case, you would have\
    a single API Definition.\
\
    <CodeBlocks>\
      <CodeBlock title="generators.yml">\
        ```yaml\
        api: path/to/petstore.yml\
        ```\
      </CodeBlock>\
\
      <CodeBlock title="TypeScript">\
        ```ts\
        client.pet.getPetById(1);\
        ```\
      </CodeBlock>\
    </CodeBlocks>\
  </Accordion>\
\
  <Accordion title="Multiple APIs">\
    If you have multiple API Definitions, you can specify them in `generators.yml` as follows:\
\
    <CodeBlocks>\
      <CodeBlock title="generators.yml">\
        ```yaml\
        api: \
          - path/to/petstore.yml\
          - path/to/plantstore.yml\
        ```\
      </CodeBlock>\
\
      <CodeBlock title="TypeScript">\
        ```ts\
        client.pet.getPetById(1);\
\
        client.plant.getPlantById(1); \
        ```\
      </CodeBlock>\
    </CodeBlocks>\
  </Accordion>\
\
  <Accordion title="Namespaced APIs">\
    If you have multiple API Definitions that have overlapping schema names or operation names,\
    you can specify a `namespace` for each API Definition. A namespace is often used to\
    handle API versioning. Note these are nested under a `namespaces` block.\
\
    <CodeBlocks>\
      <CodeBlock title="generators.yml">\
        ```yaml \{3,6\}\
        api: \
          namespaces:\
            v1: \
              - path/to/petstore.yml\
              - path/to/plantstore.yml\
            v2: \
              - path/to/petstore-v2.yml\
              - path/to/plantstore-v2.yml\
        ```\
      </CodeBlock>\
\
      <CodeBlock title="TypeScript">\
        ```ts\
        client.v1.pet.getPetById(1);\
\
        client.v2.plant.getPlantById(1); \
        ```\
      </CodeBlock>\
    </CodeBlocks>\
  </Accordion>\
\
  <Accordion title="Depending on APIs">\
    Fern allows you to import other APIs into your API. This is often useful if:\
\
    * you want to reuse another API\'92s types in your API\
    * you want to combine multiple APIs into one SDK (similar to the AWS SDK)\
\
    <Note>\
      This feature is only available if you use a Fern Definition.\
    </Note>\
\
    <Steps>\
      ### Register your API\
\
      The first step is to register the API you want to depend on. To do this, use\
      the register command:\
\
      ```bash\
      fern register\
        [some-dependency]: Uploading definition...\
        [some-dependency]: Registered @fern/some-dependency:0.0.1\
      ```\
\
      You can set the version of your dependency by using the `--version` flag:\
\
      ```bash\
      fern register --version 1.0.0\
        [some-dependency]: Uploading definition...\
        [some-dependency]: Registered @fern/some-dependency:1.0.0\
      ```\
\
      ### Depending on the registered API\
\
      To add a dependency on another API, you simply create a folder in your Fern Definition to\
      \'93house\'94 the dependency.\
\
      ```bash\
      fern/\
        \uc0\u9500 \u9472  fern.config.json\
        \uc0\u9492 \u9472  api/ # <--- your API\
          \uc0\u9500 \u9472  generators.yml\
          \uc0\u9492 \u9472  definition/\
            \uc0\u9500 \u9472  api.yml\
            \uc0\u9500 \u9472  imdb.yml\
            \uc0\u9492 \u9472  my-folder\
              \uc0\u9492 \u9472  __package__.yml\
      ```\
\
      In `__package__.yml`, you can specify the API you want to depend on:\
\
      ```yaml\
      export:\
      name: @fern/some-dependency\
      version: 0.0.1\
      ```\
\
      At runtime, the `__package__.yml` file will effectively\
      be replaced with the API you\'92re depending on.\
    </Steps>\
  </Accordion>\
</AccordionGroup>\
\
\
# WebSockets\
\
> Send and receive messages over WebSockets\
\
<Warning title="Pro Feature">\
  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)\
  or [email us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
Fern's SDKs support sending and receiving messages over WebSockets. You can specify\
your WebSocket API Definition by using [AsyncAPI](https://www.asyncapi.com/en) or\
the Fern Definition.\
\
### How it works\
\
<Steps>\
  ### Specify your WebSocket API Definition\
\
  <AccordionGroup>\
    <Accordion title="AsyncAPI">\
      See below for how to specify the contract for your WebSocket channel\
      using AsyncAPI.\
\
      ```yaml maxLines=\{0\}\
          asyncapi: 2.6.0\
          info:\
            title: Chat API\
            version: 1.1.2\
          servers:\
            production:\
              host: wss.chat.com\
          channels:\
            /:\
              bindings:\
                ws:\
                  query:\
                    type: object\
                    properties:\
                      channel_id:\
                        type: string\
                        description: Unique identifier assigned to the channel\
              publish:\
                description: Send messages to the WebSocket\
                operationId: sendMessage\
                message:\
                  oneOf:\
                    - $ref: "#/components/messages/SendChat"\
              subscribe:\
                description: Receive messages from the WebSocket\
                operationId: receiveMessage\
                message:\
                  oneOf:\
                    - $ref: "#/components/messages/ReceiveChat"\
          components:\
            messages:\
              SendChat:\
                summary: Action triggered when the channel receives a new reaction-added event\
                payload:\
                  $ref: '#/components/schemas/SendChat'\
              ReceiveChat:\
                summary: Action triggered when a successful WebSocket connection is established\
                payload:\
                  $ref: '#/components/schemas/ReceiveChat'\
          schemas:\
            SendChat:\
              type: object\
              properties:\
                message:\
                  type: string\
            ReceiveChat:\
              type: object\
              properties:\
                message:\
                  type: string\
      ```\
    </Accordion>\
\
    <Accordion title="Fern Definition">\
      If you have a Fern Definition, you can specify your websocket in\
      a yaml file. See the example in `chat.yml` below:\
\
      <CodeBlocks>\
        <CodeBlock title="chat.yml">\
          ```yaml maxLines=\{0\}\
          channel: \
            query-parameters: \
              channel_id: \
                type: string\
                docs: Unique identifier assigned to the channel\
            messages: \
              send: \
                payload: \
                  message: \
                    type: string\
                    docs: The message to send over the WebSocket\
              receive: \
                payload: \
                  message: string\
          ```\
        </CodeBlock>\
      </CodeBlocks>\
    </Accordion>\
  </AccordionGroup>\
\
  ### Generate the SDK\
\
  <CodeBlocks>\
    <CodeBlock title="TypeScript">\
      ```ts maxLines=\{0\}\
      import \{ ChatClient \} from "chat";\
\
      const client = new ChatClient();\
\
      const socket = client.chat.connect(\{\
        channelId: "123",\
        onOpen: () => \{\
          console.log("Connected to the WebSocket");\
        \},\
        onMessage: (message) => \{\
          console.log(message);\
        \},\
      \});\
\
      await socket.send("Hello, world!");\
\
      socket.on("close", () => \{\
        console.log("WebSocket connection closed");\
      \});\
\
      await socket.send("Bye, world!");\
\
      socket.close();\
      ```\
    </CodeBlock>\
\
    <CodeBlock title="Python">\
      ```python\
      from chat.client import Chat  \
\
      client = Chat()\
\
      async with client.chat.connect(\
                    channel_id="123", \
                    on_message: lambda message: print(message)) as socket:\
        \
          await socket.send("Hello, world!")\
\
          response = await socket.recv()\
\
          await socket.send("Bye, world!");\
      ```\
    </CodeBlock>\
  </CodeBlocks>\
</Steps>\
\
\
# SDK Configuration\
\
> Configure your SDK generators in `generators.yml` and publish to registries\
\
<Note>\
  Before you can configure your generators, you must setup your API Definition. Learn more\
  [**here**](/learn/api-definition/introduction/what-is-the-fern-folder)\
</Note>\
\
## Top Level Configuration\
\
```yaml title="generators.yml" maxLines=10\
default-group: local\
\
readme:\
  apiReferenceLink: https://plantstore.dev\
  defaultEndpoint: GET /v3/store/inventory\
\
groups:\
  node:\
    generators:\
      - name: fernapi/fern-typescript-node-sdk\
        version: 0.x.x\
        output:\
          location: npm\
          package-name: "@plantstore/sdk"\
          token: $\{NPM_TOKEN\}\
        config:\
          outputSourceFiles: true\
        github:\
          repository: "plantstore/plantstore-js"\
        metadata:\
          package-description: JavaScript library for the Plant Store API Service\
          license: MIT\
  python:\
    generators:\
      - name: fernapi/fern-python-sdk\
        version: 0.x.x\
        output:\
          location: pypi\
          package-name: "plantstore"\
          token: $\{PYPI_TOKEN\}\
        config:\
          outputSourceFiles: true\
        github:\
          repository: "plantstore/plantstore-python"\
```\
\
<ParamField path="default-group" type="string" required=\{false\}>\
  The default group of generators to run when running `fern generate`.\
</ParamField>\
\
<ParamField path="readme" type="object" required=\{false\}>\
  Learn more about the README configuration [here](#readme-configuration).\
</ParamField>\
\
<ParamField path="groups" type="map<string, GroupConfiguration>" required=\{false\}>\
  A set of key-value pairs from the group id to the group configuration.\
</ParamField>\
\
## README Configuration\
\
```yaml generators.yml\
readme:\
  apiReferenceLink: https://plantstore.dev\
  defaultEndpoint: GET /v3/store/inventory\
```\
\
<ParamField path="readme.apiReferenceLink" type="string" required=\{false\}>\
  A link to your hosted API Reference. Fern will embed this link into your generated READMEs so that SDK users know to\
  navigate to your API Reference.\
</ParamField>\
\
<ParamField path="readme.defaultEndpoint" type="ReadMe Configuration" required=\{false\}>\
  The endpoint you want to use in README code samples. If unspecified, Fern will default to the first POST request.\
</ParamField>\
\
## Specify Package Metadata\
\
```yaml generators.yml\
metadata:\
  package-description: Python library for the Plant Store API Service\
  license: Apache\
```\
\
<ParamField path="generator.metadata.package-description" type="string" required=\{false\}>\
  The decription you'd like the package manager, such as NPM or PyPI, to include.\
</ParamField>\
\
<ParamField path="generator.metadata.license" type="License" required=\{false\}>\
  The license you'd like to apply to the code published to GitHub. Options include `MIT` or `Apache` (Apache 2.0). To\
  request a new license, [open a GitHub\
  Issue](https://github.com/fern-api/fern/issues/new?assignees=\\&labels=\\&projects=\\&template=feature-request.md\\&title=%5BFeature%5D).\
</ParamField>\
\
## Schema Validation\
\
Add the following as a comment in your `generators.yml` to enable schema validation, ensuring that your configuration is correct. Check out an example in [Cartesia's Fern Folder](https://github.com/cartesia-ai/docs/blob/43b143f66845d90bffbd0ef1951fd812229d95c0/fern/generators.yml#L1).\
\
```yaml\
yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json\
```\
\
\
# Generate your first SDK\
\
> Use Fern's CLI tool to generate your first SDK.\
\
<Warning title="Schedule a Demo">\
  Generating SDKs often requires understanding the state of your OpenAPI Specification as well as\
  your specific requirements. For the ideal experience, we **strongly recommend** scheduling a\
  [demo](https://buildwithfern.com/contact) or [emailing us](mailto:support@buildwithfern.com) to get started.\
</Warning>\
\
If you'd rather get started immediately, you can use Fern's CLI tool\
to generate your first SDK.\
\
<Steps>\
  ### Install the Fern CLI\
\
  First, install the CLI tool by running the following command:\
\
  ```bash\
  npm install -g fern-api\
  ```\
\
  ### Initialize the Fern Folder\
\
  <AccordionGroup>\
    <Accordion title="OpenAPI">\
      If you have an OpenAPI Specification, you can initialize the Fern folder by running the following command:\
\
      ```bash\
      fern init --openapi path/to/openapi.yml\
      ```\
\
      If your OpenAPI Specification is hosted on the web, you can use the URL:\
\
      ```bash\
      fern init --openapi https://api.example.com/openapi.yml\
      ```\
\
      This will create a `fern` folder in your current directory with the OpenAPI Specification.\
\
      ```bash\
      fern/\
        \uc0\u9500 \u9472  fern.config.json # root-level configuration\
        \uc0\u9492 \u9472  api/ # your API\
          \uc0\u9500 \u9472  generators.yml # generators you're using\
          \uc0\u9492 \u9472  openapi/\
            \uc0\u9500 \u9472  openapi.yml  # API-level configuration\
      ```\
    </Accordion>\
\
    <Accordion title="Fern Definition">\
      If you'd like to use the Fern Definition, you can initialize the Fern folder\
      by running the following command:\
\
      ```bash\
      fern init\
      ```\
\
      This will create a `fern` folder in your current directory with the Fern Definition.\
\
      ```bash\
      fern/\
        \uc0\u9500 \u9472  fern.config.json # root-level configuration\
        \uc0\u9500 \u9472  generators.yml # generators you're using\
        \uc0\u9492 \u9472  definition/\
          \uc0\u9500 \u9472  api.yml  # API-level configuration\
          \uc0\u9492 \u9472  imdb.yml # endpoints, types, and errors\
      ```\
    </Accordion>\
  </AccordionGroup>\
\
  ### Pass `fern check`\
\
  Run `fern check` to ensure that your API Definition is valid. If there are any errors,\
  you will need to fix them before proceeding.\
\
  <Note>\
    If you're using an OpenAPI Specification, check out all of our\
    [supported extensions](/learn/api-definition/openapi/extensions).\
  </Note>\
\
  ### Add the SDK generator\
\
  <Warning title="Pro Features">\
    By default, none of the pro features will be enabled.\
  </Warning>\
\
  You can now use the SDK in your application. Here's an example of how\
  you can use the SDK:\
\
  <CodeBlocks>\
    <CodeBlock title="TypeScript">\
      ```sh\
      fern add fern-typescript-node-sdk --group sdk\
      ```\
    </CodeBlock>\
\
    <CodeBlock title="Python">\
      ```sh\
      fern add fern-python-sdk --group sdk\
      ```\
    </CodeBlock>\
\
    <CodeBlock title="Java">\
      ```sh\
      fern add fern-java-sdk --group sdk\
      ```\
    </CodeBlock>\
\
    <CodeBlock title="Go">\
      ```sh\
      fern add fern-go-sdk --group sdk\
      ```\
    </CodeBlock>\
\
    <CodeBlock title="Ruby">\
      ```sh\
      fern add fern-ruby-sdk --group sdk\
      ```\
    </CodeBlock>\
\
    <CodeBlock title="C#">\
      ```sh\
      fern add fern-csharp-sdk --group sdk\
      ```\
    </CodeBlock>\
  </CodeBlocks>\
\
  ### Run `fern generate --group sdk`\
\
  Next up, run the following command to generate the SDK:\
\
  ```bash\
  fern generate --group sdk\
  ```\
\
  This will create a `fern` folder in your current directory with the Fern\
  Definition. For example, if you're generating a TypeScript SDK, the folder structure\
  will look like this:\
\
  ```bash\
  sdks/\
    typescript/\
      src/\
        \uc0\u9500 \u9472  index.ts\
        \uc0\u9500 \u9472  Client.ts\
        \uc0\u9492 \u9472  api\
        \uc0\u9492 \u9472  errors   \
        \uc0\u9492 \u9472  serialization   \
  ```\
</Steps>\
\
\
# Preview your SDK\
\
> Use Fern's CLI tool to preview your SDK locally.\
\
[Once you configure your SDK](/learn/sdks/getting-started/generate-your-first-sdk), you can preview the generated SDK code using Fern's CLI.\
\
Simply append the `--preview` flag to the command used to generate the SDK and you will see the generated code populated in a `.preview` folder within your `fern` folder.\
\
<Tip title="Custom Code">\
  [If you have added custom code to your SDK](/learn/sdks/capabilities/augment-with-custom-code), `--preview` will\
  preserve those changes.\
</Tip>\
\
Here's an example of how you can preview your SDK:\
\
<Steps>\
  ### Generator configuration\
\
  ```yaml generators.yml\
  api: \
    path: ./path/to/openapi.yml\
  groups:\
    python-sdk:\
      generators:\
        - name: fernapi/fern-python-sdk\
          version: 3.0.0\
          output:\
            location: pypi\
            package-name: imdb\
            token: $\{PYPI_TOKEN\}\
          github:\
            repository: imdb/imdb-python\
          config:\
            client_class_name: imdb\
  ```\
\
  ### Invoke the Fern CLI\
\
  ```shell\
  fern generate --group python-sdk --preview\
  ```\
\
  ### Preview your SDK\
\
  The resulting folder structure will look like this:\
\
  <Tabs>\
    <Tab title="OpenAPI">\
      ```shell \{3-5\}\
      fern/\
        \uc0\u9500 \u9472  fern.config.json\
        \uc0\u9500 \u9472  .preview/\
          \uc0\u9492 \u9472  fern-python-sdk/\
            \uc0\u9492 \u9472  ...\
        \uc0\u9500 \u9472  generators.yml\
        \uc0\u9492 \u9472  openapi/\
          \uc0\u9492 \u9472  openapi.yml\
      ```\
    </Tab>\
\
    <Tab title="Fern Definition">\
      ```shell \{3-5\}\
      fern/\
        \uc0\u9500 \u9472  fern.config.json\
        \uc0\u9500 \u9472  .preview/\
          \uc0\u9492 \u9472  fern-python-sdk/\
            \uc0\u9492 \u9472  ...\
        \uc0\u9500 \u9472  generators.yml\
        \uc0\u9492 \u9472  definition/\
          \uc0\u9500 \u9472  api.yml\
          \uc0\u9492 \u9472  imdb.yml\
      ```\
    </Tab>\
  </Tabs>\
</Steps>\
\
\
# Publish a public-facing SDK\
\
> Use Fern to publish a public-facing SDK\
\
<Frame caption="Merge.dev uses Fern for their SDKs">\
  <img alt="GitHub Page" src="file:3f9df796-fd0b-4c4d-b228-ee9d9b8b6df4" />\
</Frame>\
\
This guide will walk you through how to publish public-facing SDKs through Fern.\
\
<Steps>\
  ### Navigate to your `generators.yml`\
\
  This guide assumes that you already have an initialized fern folder. If you don't\
  please run `fern init`!\
\
  Your `generators.yml` lives inside of the fern folder and contains all\
  the configuration for your Fern generators.\
\
  ### Run `fern add <generator>`\
\
  In order to generate the SDK, we'll need to add the generator to your\
  `generators.yml`. You can use the `fern <add>` command to do this.\
\
  <CodeBlocks>\
    ```bash TypeScript\
    fern add fern-typescript-node-sdk --group ts-sdk\
    ```\
\
    ```bash Python\
    fern add fern-python-sdk --group python-sdk\
    ```\
\
    ```bash Java\
    fern add fern-java-sdk --group java-sdk\
    ```\
\
    ```bash Go\
    fern add fern-go-sdk --group go-sdk\
    ```\
  </CodeBlocks>\
\
  Once the command completes, you'll see a new group created in your `generators.yml`.\
\
  <CodeBlocks>\
    ```yaml TypeScript \
    groups: \
      ts-sdk:\
        generators:\
          - name: fernapi/fern-typescript-node-sdk\
            version: 0.9.5\
            output:\
              location: local-file-system\
              path: ../sdks/typescript\
    ```\
\
    ```yaml Python \
    groups: \
      python-sdk:\
        generators:\
          - name: fernapi/fern-python-sdk\
            version: 0.8.1\
            output:\
              location: local-file-system\
              path: ../sdks/python\
    ```\
\
    ```yaml Java \
    groups: \
      java-sdk:\
        generators:\
          - name: fernapi/fern-java-sdk\
            version: 0.9.1\
    ```\
\
    ```yaml Go \
    groups:\
      go-sdk:\
        generators:\
          - name: fernapi/fern-go-sdk\
            version: 0.9.1\
    ```\
  </CodeBlocks>\
\
  Here are the [latest versions of each generator](https://github.com/fern-api/fern?tab=readme-ov-file#-generators).\
\
  ### Configure `output` location\
\
  In order to setup publishing your SDK, you'll need to configure\
  an output location in your `generators.yml`.\
\
  <CodeBlocks>\
    ```yaml title="TypeScript" \{6-9\}\
    groups: \
      ts-sdk:\
        generators:\
          - name: fernapi/fern-typescript-node-sdk\
            version: 0.9.5\
            output:\
              location: npm\
              package-name: imdb\
              token: $\{NPM_TOKEN\} # reads from environment\
    ```\
\
    ```yaml title="Python" \{6-9\}\
    groups: \
      python-sdk:\
        generators:\
          - name: fernapi/fern-python-sdk\
            version: 0.8.1\
            output:\
              location: pypi\
              package-name: imdb\
              token: $\{PYPI_TOKEN\} # reads from environment\
    ```\
\
    ```yaml title="Java" \{9-12\}\
    groups: \
      java-sdk:\
        generators:\
          - name: fernapi/fern-java-sdk\
            version: 0.9.1\
            output:\
              location: maven\
              artifact: com.imdb:imdb-java\
              username: $\{MAVEN_USERNAME\} # reads from environment\
              password: $\{MAVEN_PASSWORD\} # reads from environment\
    ```\
  </CodeBlocks>\
\
  ### Install GitHub app\
\
  To configure the Github integration you must (1) **create a Github repository** and (2) **install the [Fern GitHub App](https://github.com/apps/fern-api)**.\
\
  ### Configure `GitHub` location\
\
  Once you've created the Github repository you must add it to your `generators.yml`:\
\
  ```yaml title="TypeScript" \{10-11\}\
  groups: \
    ts-sdk:\
      generators:\
        - name: fernapi/fern-typescript-node-sdk\
          version: 0.9.5\
          output:\
            location: npm\
            package-name: imdb\
            token: $\{NPM_TOKEN\} \
          github: \
            repository: your-org/your-repository\
  ```\
\
  ### Run `fern generate`\
\
  At this point, you are ready to go and can run `fern generate --version <version>`.\
\
  <Warning>\
     Make sure that any environment variables like \
\
    `NPM_TOKEN`\
\
     are present! \
  </Warning>\
\
  ### Setup a GitHub Action\
\
  We strongly advise adding a GitHub Action to trigger SDK releases for each language. Below is\
  an example of how you might setup a workflow\\_dispatch\
\
  <CodeBlocks>\
    ```yaml title="Python" maxLines=0\
    name: python-sdk\
\
    on:\
      workflow_dispatch:\
        inputs:\
          version:\
            description: "The version of the python SDK that you would like to release"\
            required: true\
            type: string\
\
    jobs:\
      release:\
        runs-on: ubuntu-latest\
        steps:\
          - name: Checkout repository\
            uses: actions/checkout@v4\
\
          - name: Install Fern\
            run: npm install -g fern-api\
\
          - name: Release Python SDK\
            env:\
              FERN_TOKEN: $\{\{ secrets.FERN_TOKEN \}\}\
              PYPI_TOKEN: $\{\{ secrets.PYPI_TOKEN \}\}\
            run: |\
              fern generate --group python-sdk --version $\{\{ inputs.version \}\} --log-level debug\
    ```\
\
    ```yaml title="TypeScript" maxLines=0\
    name: ts-sdk\
\
    on:\
      workflow_dispatch:\
        inputs:\
          version:\
            description: "The version of the TS SDK that you would like to release"\
            required: true\
            type: string\
\
    jobs:\
      release:\
        runs-on: ubuntu-latest\
        steps:\
          - name: Checkout repo\
            uses: actions/checkout@v3\
\
          - name: Setup node\
            uses: actions/setup-node@v3\
\
          - name: Download Fern\
            run: npm install -g fern-api\
\
          - name: Release Node SDK\
            env:\
              FERN_TOKEN: $\{\{ secrets.FERN_TOKEN \}\}\
              NPM_TOKEN: $\{\{ secrets.NPM_TOKEN \}\}\
            run: |\
              fern generate --group ts-sdk --version $\{\{ inputs.version \}\} --log-level debug\
    ```\
  </CodeBlocks>\
\
  Once these actions are merged in, you can simply release your SDK by navigating to the actions tab:\
\
  <img alt="GitHub Page" src="file:9e6d177b-8ce8-4b3a-930b-aba7aea1342c" width="250" height="300" />\
</Steps>\
\
\
# Publish your TypeScript SDK with npm\
\
To make your TypeScript SDK publicly accessible, publish to [npm](https://www.npmjs.com/). Once you've followed the steps below to connect your npm account to your SDK, Fern will automatically publish the latest version of your SDK.\
\
## Creating an npm token\
\
<Steps>\
  ### Log In\
\
  Log into [npm](https://www.npmjs.com/).\
\
  ### Navigate to Access Tokens\
\
  Click on your profile picture and select **Access Tokens**.\
\
  ### Generate Token\
\
  Click on **Generate New Token** and select **Classic Token**. Name your token and select **Automation** as the token type. Once finished, click **Generate Token**.\
\
  <Note title="Save your token">\
    Be sure to save the generated token - it won't be displayed after you leave the page.\
  </Note>\
</Steps>\
\
## Adding tokens to your GitHub repository\
\
<Info>\
  Using GitLab? Follow [these steps](/learn/docs/developer-tools/gitlab#add-a-token-to-gitlab).\
</Info>\
\
<Steps>\
  ### Open Repository\
\
  Open your Fern repository in GitHub.\
\
  ### Navigate to Actions in Settings\
\
  Click on the **Settings** tab in your repository. Then, under the **Security** section, open **Secrets and variables** > **Actions**.\
\
  <Frame>\
    <img src="file:a5598846-598a-4225-b783-af8a25e22aa0" alt="Adding GitHub Repository Secret" />\
  </Frame>\
\
  You can also use the url `https://github.com/<your-repo>/settings/secrets/actions`.\
\
  ### Add Secret\
\
  Select **New repository secret**. Name your secret (we recommend `NPM_TOKEN`), add the corresponding token, and click **Add secret**.\
</Steps>\
\
Once you regenerate your SDK, a GitHub action will run to publish directly to npm!\
\
\
# Publish your Python SDK with PyPI\
\
To make your Python SDK publicly accessible, publish to [PyPI](https://pypi.org/). Once you've followed the steps below to connect your PyPI account to your SDK, Fern will automatically publish the latest version of your SDK.\
\
## Creating a PyPI token\
\
<Steps>\
  ### Log In\
\
  Log into [PyPI](https://pypi.org/).\
\
  ### Navigate to Account Settings\
\
  Click on your profile picture and select **Account settings**.\
\
  ### Create API Token\
\
  Scroll down to **API tokens** and click **Create API token**. Name your token and set the scope to the relevant projects. Once finished, click **Create token**.\
\
  <Note title="Save your token">\
    Be sure to save the generated token - it won't be displayed after you leave the page.\
  </Note>\
</Steps>\
\
## Adding tokens to your GitHub repository\
\
<Info>\
  Using GitLab? Follow [these steps](/learn/docs/developer-tools/gitlab#add-a-token-to-gitlab).\
</Info>\
\
<Steps>\
  ### Open Repository\
\
  Open your Fern repository in GitHub.\
\
  ### Navigate to Actions in Settings\
\
  Click on the **Settings** tab in your repository. Then, under the **Security** section, open **Secrets and variables** > **Actions**.\
\
  <Frame>\
    <img src="file:a5598846-598a-4225-b783-af8a25e22aa0" alt="Adding GitHub Repository Secret" />\
  </Frame>\
\
  You can also use the url `https://github.com/<your-repo>/settings/secrets/actions`.\
\
  ### Add Secret\
\
  Select **New repository secret**. Name your secret (we recommend `PYPI_TOKEN`), add the corresponding token, and click **Add secret**.\
</Steps>\
\
Once you regenerate your SDK, a GitHub action will run to publish directly to PyPI!\
\
\
# Publish your C# SDK with NuGet\
\
To make your C#/.NET SDK publicly accessible, publish to [NuGet](https://www.nuget.org/). Once you've followed the steps below to connect your NuGet account to your SDK, Fern will automatically publish the latest version of your SDK.\
\
## Creating a NuGet API key\
\
<Steps>\
  ### Log In\
\
  Log into [NuGet](https://www.nuget.org/users/account/LogOn?returnUrl=%2F).\
\
  ### Navigate to API Keys\
\
  Click on your username in the top-right corner and select **API Keys**.\
\
  ### Generate API Key\
\
  * Click on **Create**.\
  * Name your key.\
  * Select **Push > Push new packages and package versions** as the **Select Scopes** type.\
  * Enter `*` under **Select Packages > Glob Patten**.\
    <Tip title="Replacing an existing NuGet package">\
      If you are overriding an existing package, you can select the relevant package instead of entering `*`.\
    </Tip>\
  * Click **Create**.\
\
  <Note title="Save your API key">\
    Be sure to save the generated key - it won't be displayed after you leave the page.\
  </Note>\
</Steps>\
\
## Adding API keys to your GitHub repository\
\
<Info>\
  Using GitLab? Follow [these steps](/learn/docs/developer-tools/gitlab#add-a-token-to-gitlab).\
</Info>\
\
<Steps>\
  ### Open Repository\
\
  Open your Fern repository in GitHub.\
\
  ### Navigate to Actions in Settings\
\
  Click on the **Settings** tab in your repository. Then, under the **Security** section, open **Secrets and variables** > **Actions**.\
\
  <Frame>\
    <img src="file:a5598846-598a-4225-b783-af8a25e22aa0" alt="Adding GitHub Repository Secret" />\
  </Frame>\
\
  You can also use the url `https://github.com/<your-repo>/settings/secrets/actions`.\
\
  ### Add Secret\
\
  Select **New repository secret**. Name your secret (we recommend `NUGET_API_KEY`), add the corresponding API key, and click **Add secret**.\
</Steps>\
\
Once you regenerate your SDK, a GitHub action will run to publish directly to NuGet!\
\
\
# Publish your Go SDK with Pkgsite\
\
To publish your Go SDK using [Pkgsite](https://pkg.go.dev/about#adding-a-package):\
\
1. Make sure the repository is set to **public** visibility\
2. Make sure you have added a required license (e.g. [MIT](https://opensource.org/license/mit), [Apache](https://www.apache.org/licenses/LICENSE-2.0)) to the repository\
3. Send a request to `https://pkg.go.dev/github.com/<github-org>/<github-repo-name>/`\
\
In a few minutes, your SDK should be published to [https://pkg.go.dev/](https://pkg.go.dev/)!\
\
\
# Publish your Java SDK with Maven\
\
To make your Java SDK publicly accessible, publish to [Maven](https://central.sonatype.com/). Once you've followed the steps below to connect your Maven account to your SDK, Fern will automatically publish the latest version of your SDK.\
\
## Creating a Maven username and password\
\
<Steps>\
  ### Log In (or create account)\
\
  Log into [s01.oss.sonatype.org](https://s01.oss.sonatype.org).\
\
  ### Navigate to your profile\
\
  Click on your username in the top-right corner and select **Profile**.\
\
  <Frame>\
    <img src="file:3f709cb5-254a-4bb5-933a-e7179b2860e5" alt="Profile selection" />\
  </Frame>\
\
  ### Click on `User Token`\
\
  Expand the dropdown and click on `User Token`.\
\
  <Frame>\
    <img src="file:72f44a75-d799-4604-86c4-dd37ff05ea43" alt="Select user token" />\
  </Frame>\
\
  ### Click on `Access User Token`\
\
  There will be a lock icon followed by the text `Access User Token`. Click on `Access User Token`. You may\
  need to re-authenticate to see the user token.\
\
  <Frame>\
    <img src="file:1cf9cff8-53c0-4412-ad07-e1705cfcbf29" alt="View your username and password" />\
  </Frame>\
\
  ### Add GitHub Secrets\
\
  You'll need to store two repository secrets in your **fern configuration repository** (**i.e. not the Java SDK repository**),\
  one for the username and one for the password.\
\
  <Frame>\
    <img src="file:a5598846-598a-4225-b783-af8a25e22aa0" alt="Adding GitHub Repository Secret" />\
  </Frame>\
\
  <Info>\
    For each, select **New repository secret**. Name your secret (we recommend `MAVEN_USERNAME` and `MAVEN_PASSWORD`,\
    respectively), add the corresponding value, and click **Add secret**.\
  </Info>\
</Steps>\
\
Once you regenerate your SDK, a GitHub action will run to publish directly to Maven!\
\
\
# Publish your Ruby SDK with RubyGems\
\
To make your Ruby SDK publicly accessible, publish to [RubyGems](https://rubygems.org/). Once you've followed the steps below to connect your Ruby account to your SDK, Fern will automatically publish the latest version of your SDK.\
\
## Creating a RubyGems API key\
\
<Steps>\
  ### Log In\
\
  You'll first need to [create an account with RubyGems](https://rubygems.org/sign_up) to register your SDK.\
\
  If you have an account already, [sign in](https://rubygems.org/sign_in).\
\
  ### Navigate to API Keys\
\
  Click on your username in the top-right corner and select **Settings**. Then scroll down and click on [**API Keys**](https://rubygems.org/profile/api_keys).\
\
  ### Create an API key\
\
  When prompted to [create a new API key](https://rubygems.org/profile/api_keys/new):\
\
  * Name your key.\
  * Under **Scopes**, select **Push rubygem**\
  * Select `All Gems` under **Gem Scope**.\
    <Tip title="Replacing an existing gem">\
      If you are overriding an existing gem, you can select the relevant package instead of entering `All Gems`.\
    </Tip>\
  * Set an expiration date.\
  * Click **Create API Key**.\
\
  <Note title="Save your API key">\
    Be sure to save the generated key - it won't be displayed after you leave the page.\
  </Note>\
</Steps>\
\
## Adding API keys to your GitHub repository\
\
<Info>\
  Using GitLab? Follow [these steps](/learn/docs/developer-tools/gitlab#add-a-token-to-gitlab).\
</Info>\
\
<Steps>\
  ### Open Repository\
\
  Open your Fern repository in GitHub.\
\
  ### Navigate to Actions in Settings\
\
  Click on the **Settings** tab in your repository. Then, under the **Security** section, open **Secrets and variables** > **Actions**.\
\
  <Frame>\
    <img src="file:a5598846-598a-4225-b783-af8a25e22aa0" alt="Adding GitHub Repository Secret" />\
  </Frame>\
\
  You can also use the url `https://github.com/<your-repo>/settings/secrets/actions`.\
\
  ### Add Secret\
\
  Select **New repository secret**. Name your secret (we recommend `RUBYGEMS_API_KEY`), add the corresponding API key, and click **Add secret**.\
</Steps>\
\
Once you regenerate your SDK, a GitHub action will run to publish directly to RubyGems!\
\
\
# Publish your PHP SDK with Packagist\
\
To make your PHP SDK publicly accessible, publish to [Packagist](https://packagist.org/). Follow the steps below to connect your GitHub repository to Packagist.\
\
<Steps>\
  ### Create a Packagist account\
\
  You'll first need to [create an account with Packagist](https://packagist.org/register/) to register your SDK.\
\
  If you have an account already, [sign in](https://packagist.org/login/).\
\
  ### Submit the repository URL\
\
  When prompted, input the full URL of the repository where the PHP SDK was generated.\
\
  <Tip>\
    Be sure your repository has **public** visibility. You can configure this in the repository settings.\
  </Tip>\
\
  ### Configure the GitHub Hook\
\
  Once you've submitted your URL, you'll be prompted to set up the GitHub Hook.\
\
  <Frame>\
    <img src="file:5e42db92-4341-4264-a330-247df1f616de" />\
  </Frame>\
\
  Follow the instructions to [set up your GitHub Hook](https://packagist.org/about#how-to-update-packages):\
\
  1. In to your repository, go to **Settings > Webhooks**.\
  2. Select **"Add webhook"**\
  3. Set the Payload URL as `https://packagist.org/api/github?username=<your.packagist.username>`\
  4. Set the content type as `application/json`\
  5. Add your [Packagist API key](https://packagist.org/profile/).\
  6. Set the trigger events as **Just the `push` event**\
  7. Click **"Add Webhook"**\
\
  <Frame>\
    <img src="file:7ac84e2a-f021-4f61-b1bc-b21e29ea6127" />\
  </Frame>\
</Steps>\
\
Once you regenerate your SDK, you will see the publish occur!\
\
\
# Quickstart\
\
> Start building beautiful documentation in under 5 minutes\
\
<img alt="Docs cascade" src="file:1d952cf3-6053-4862-8f0b-65bba22c0c95" />\
\
With Fern, you can build beautiful developer documentation that matches your brand. Fern supports writing pages (written in Markdown) and generating API Reference documentation (from an OpenAPI Specification).\
\
In this guide, we'll show you how to get started with Fern in under 5 minutes.\
\
<Steps toc=\{true\}>\
  ### Initialize your `fern` folder\
\
  All the configuration for your docs lives in the `fern` folder. Inside you'll\
  find a `docs.yml` file that contains all the settings for your documentation.\
\
  <AccordionGroup toc=\{true\}>\
    <Accordion title="Clone the starter repository">\
      Get started by cloning the [starter template](https://github.com/fern-api/docs-starter-openapi).\
\
      ```bash\
      git clone git@github.com:fern-api/docs-starter-openapi.git\
      ```\
\
      Next, please update the template settings to use your organization.\
\
      <Warning title="Edit template settings">\
        Please edit the details `fern.config.json` and `docs.yml` with your organization\
        name.\
\
        <CodeBlocks>\
          <CodeBlock title="fern.config.json">\
            ```json \{2\}\
            \{\
              "organization": "\{\{YOUR_ORGANIZATION\}\}",\
              "version": "0.x.x"\
            \}\
            ```\
          </CodeBlock>\
\
          <CodeBlock title="docs.yml">\
            ```yml \{2\}\
            instances:\
              - url: \{\{YOUR_ORGANIZATION\}\}.docs.buildwithfern.com\
            ```\
          </CodeBlock>\
        </CodeBlocks>\
      </Warning>\
\
      Finally, run `fern generate --docs` to generate your documentation.\
    </Accordion>\
\
    <Accordion title="Use the Fern CLI">\
      If you prefer, you can use our CLI to create a new project. Install the CLI\
      by running\
\
      ```bash\
      npm install -g fern-api\
      ```\
\
      Then run\
\
      ```bash\
      fern init --docs\
      ```\
\
      You will see a new `fern` folder in your project with the following structure:\
\
      ```bash\
        fern\
        \uc0\u9500 \u9472  docs.yml\
        \uc0\u9492 \u9472  fern.config.json\
      ```\
\
      Finally, run `fern generate --docs` to generate your documentation.\
    </Accordion>\
  </AccordionGroup>\
\
  ### Update your docs\
\
  <Note>\
    We provide a white-glove migration service as part of our Enterprise plan. Interested? Request it\
    [here](https://buildwithfern.com/contact).\
  </Note>\
\
  <AccordionGroup toc=\{true\}>\
    <Accordion title="Add content">\
      Add content with MDX files.\
\
      ```markdown\
      ---\
      title: "Page Title"\
      description: "Subtitle (optional)" \
      ---\
\
      Hello world!\
      ```\
\
      <Note title="Supported Syntax">\
        Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required.\
      </Note>\
\
      In order for the Markdown page to show up, you'll need to reference them from your `docs.yml` file. You\
      can reference the Markdown page within a section or as a standalone page.\
\
      ```yml\
      navigation:\
        - page: "Hello World"\
          path: "pages/hello-world.mdx"\
        - section: Overview\
          content:\
            - page: QuickStart\
              path: pages/hello-world.mdx\
      ```\
    </Accordion>\
\
    <Accordion title="Add an API Reference">\
      Add an API Reference by adding an OpenAPI Specification to your project.\
\
      ```bash\
      fern init --openapi /path/to/openapi.yml\
      ```\
\
      This will create an `openapi.yml` file in your project. You can reference this file in your\
      `docs.yml` file by adding an api block.\
\
      ```yml\
      navigation:\
        - api: "API Reference"\
      ```\
    </Accordion>\
\
    <Accordion title="Brand your docs">\
      All of the branding for your docs can be configured in the `docs.yml` file.\
\
      For example, to set the logos, colors, and fonts for your docs, you can\
      add the following to your `docs.yml` file:\
\
      <CodeBlock title="docs.yml">\
        ```yml\
        colors:\
          accentPrimary:\
            dark: "#f0c193"\
            light: "#af5f1b"\
\
        logo:\
          dark: ./docs/assets/logo-dark.svg\
          light: ./docs/assets/logo-light.svg\
          height: 40\
          href: https://buildwithfern.com/\
\
        favicon: ./docs/assets/favicon.png\
        ```\
      </CodeBlock>\
    </Accordion>\
  </AccordionGroup>\
\
  ### Publish to production\
\
  <AccordionGroup toc=\{true\}>\
    <Accordion title="Host on a custom domain">\
      Fern supports hosting your docs website on a custom domain or on a\
      custom subpath (e.g. [https://domain.com/docs](https://domain.com/docs)).\
\
      Please reach out to the Fern team at [support@buildwithfern.com](mailto:support@buildwithfern.com) to configure this.\
    </Accordion>\
\
    <Accordion title="Configure analytics">\
      Fern supports integrations with a variety of providers such as PostHog, Segment, Intercom,\
      Google Tag Manager, etc.\
      Find out more on this [page](/learn/docs/integrations/overview).\
    </Accordion>\
  </AccordionGroup>\
</Steps>\
\
Below are some examples of documentation websites that have been published using Fern:\
\
<CardGroup cols=\{3\}>\
  <Card title="Hume" href="https://dev.hume.ai/intro" icon=\{<img src="https://www.hume.ai/icons/icon-144x144.png" alt="Hume logo" />\} />\
\
  <Card\
    title="Primer"\
    href="https://primer.io/docs/api"\
    icon=\{\
      <img\
        src="https://assets-global.website-files.com/65bcc4714739c54deeb9bac7/65d7663e0ceca67e8b5709c5_favicon.png"\
        alt="Primer logo"\
      />\
    \}\
  />\
\
  <Card title="AssemblyAI" href="https://www.assemblyai.com/docs/api-reference" icon=\{<img src="https://www.assemblyai.com/favicon.png" alt="AssemblyAI logo" />\} />\
\
  <Card title="SuperAgent" href="https://docs.superagent.sh/" icon=\{<img src="https://framerusercontent.com/images/P75NaYul3IVsoMqx4RMALvngO4.png" alt="SuperAgent logo" />\} />\
\
  <Card title="MultiOn" href="https://docs.multion.ai/" icon=\{<img src="https://www.multion.ai/android-chrome-192x192.png" alt="MultiOn logo" />\} />\
\
  <Card\
    title="Coactive"\
    href="https://docs.coactive.ai/"\
    icon=\{\
      <img\
        src="https://images.prismic.io/coactive/6d31b17f-cabb-492d-93ef-a9f42e03aaa2_coactive-logo-home.png?ixlib=gatsbyFP&auto=compress%2Cformat&fit=max"\
        alt="Coactive logo"\
      />\
    \}\
  />\
\
  <Card\
    title="Zep"\
    href="https://help.getzep.com/"\
    icon=\{\
      <img\
        src="https://assets-global.website-files.com/660b1c076d13b7e2967a499d/660c6dc329d8b16a8468f5ba_Asset%2017.png"\
        alt="Zep logo"\
      />\
    \}\
  />\
\
  <Card\
    title="Rightbrain"\
    href="https://docs.rightbrain.ai/intro"\
    icon=\{\
      <img\
        src="https://fdr-prod-docs-files-public.s3.amazonaws.com/https://rightbrain.docs.buildwithfern.com/2024-08-05T10:16:06.892Z/docs/assets/Logo.png"\
        alt="Rightbrain logo"\
      />\
    \}\
  />\
</CardGroup>\
\
\
# Global Configuration\
\
> Customize your documentation using the docs.yml file\
\
<Note>\
  Not all of the properties in `docs.yml` are documented here. If you'd like to see all properties, please check out the\
  the  raw [schema](https://github.com/fern-api/fern/blob/69e74d9c27dc031ec2e84e70b878c40e9e9678a5/packages/cli/configuration/fern/definition/docs.yml#L110-L153)\
</Note>\
\
## Top-level properties\
\
Every Fern documentation website needs a `docs.yml` file with the core configuration settings.\
\
```yaml docs.yml\
\
title: My Docs\
\
logo: \
  href: mydomain.com\
  dark: path/to/logo.png\
  light: path/to/logo.png\
\
favicon: path/to/favicon.ico\
\
```\
\
<ParamField path="title" type="string" required=\{false\}>\
  A string that is used as the tab bar title.\
</ParamField>\
\
<ParamField path="logo" type="object" required=\{false\}>\
  Learn more about the `logo` configuration [here](/learn/docs/getting-started/global-configuration#logo-configuration).\
</ParamField>\
\
<ParamField path="favicon" type="string" required=\{false\}>\
  Relative filepath to the favicon.\
</ParamField>\
\
<ParamField path="colors" type="objects" required=\{true\}>\
  Configure the `primaryAccent` and `background` colors. Learn more about the `colors` configuration\
  [here](/learn/docs/getting-started/global-configuration#colors-configuration).\
</ParamField>\
\
<ParamField path="redirects" type="list of objects" required=\{false\}>\
  An array of paths you want to configure to permanently redirect to another path. Learn more about the\
  `redirects` configuration [here](/learn/docs/getting-started/global-configuration#redirects-configuration).\
</ParamField>\
\
<ParamField path="navbar-links" type="list of objects" required=\{false\}>\
  Array of names and urls of links you want to include as a call to action. Learn more about the\
  `navbar-links` configuration [here](/learn/docs/getting-started/global-configuration#navbar-links-configuration).\
</ParamField>\
\
<ParamField path="background-image" type="object" required=\{false\}>\
  Set a custom background image to be displayed behind every page. Learn more about the\
  `background-image` configuration [here](/learn/docs/getting-started/global-configuration#background-image-configuration).\
</ParamField>\
\
<ParamField path="typography" type="object" required=\{false\}>\
  Customize the fonts used in your documentation website. Learn more about the\
  `typography` configuration [here](/learn/docs/getting-started/global-configuration#typography-configuration).\
</ParamField>\
\
<ParamField path="layout" type="object" required=\{false\}>\
  Customize the layout of your documentation website. Learn more about the\
  `layout` configuration [here](/learn/docs/getting-started/global-configuration#layout-configuration).\
</ParamField>\
\
<ParamField path="landing-page" type="object" required=\{false\}>\
  Creates a landing page for your documentation website. Learn more about the\
  `landing-page` configuration [here](/learn/docs/getting-started/global-configuration#landing-page-configuration).\
</ParamField>\
\
<ParamField path="default-language" type="string" required=\{false\}>\
  Sets the default language displayed by code snippets in the API Reference.\
\
  Options include: `typescript`, `python`, `java`, `go`, `ruby`, `csharp`, `curl`\
</ParamField>\
\
## Instances configuration\
\
An `instance` is the backend of a distinct docs website. Each instance is published to a unique domain using the `--instance` flag. It is most common to use instances to configure staging and production docs which publish to separate URLs.\
\
```yaml docs.yml\
instances: \
  - url: plantstore.docs.buildwithfern.com\
    custom-domain: docs.plantstore.com\
    edit-this-page: \
      github: \
        owner: fern\
        repo: plant-store-docs\
        branch: main\
```\
\
<ParamField path="instances.url" type="string" required=\{true\}>\
  The URL where your Fern documentation is deployed. Must contain the suffix `docs.buildwithfern.com`\
</ParamField>\
\
<ParamField path="instances.custom-domain" type="string or list of strings" required=\{false\}>\
  The custom domain where your documentation is hosted. Learn more about setting up a custom domain [here](/learn/docs/building-your-docs/custom-domain).\
</ParamField>\
\
<ParamField path="instances.edit-this-page" type="object" required=\{false\}>\
  If `edit-this-page` is set, Fern will add an "Edit this page" link to the bottom of each page that links to the given public GitHub repository.\
\
  Learn more about the `edit-this-page` object [here](#github-configuration).\
</ParamField>\
\
## Colors configuration\
\
```yaml docs.yml\
colors: \
  accent-primary: \
    light: "#418326"\
    dark: "#ADFF8C"\
  background: \
    light: "#ffffff"\
    dark: "#0d0e11"   \
```\
\
<ParamField path="accent-primary" type="object" required=\{true\}>\
  The configured accent primary color for light and dark mode.\
</ParamField>\
\
<ParamField path="background" type="object" required=\{false\}>\
  The configured background colors for light and dark mode.\
</ParamField>\
\
<ParamField path="border" type="object" required=\{false\}>\
  The border color is used for the borders of cards and other elements.\
</ParamField>\
\
<ParamField path="sidebar-background" type="object" required=\{false\}>\
  If `sidebarBackground` is set, the sidebar will also render a 1px border on the right side.\
\
  By default, the sidebar will render with a transparent background without a border.\
</ParamField>\
\
<ParamField path="header-background" type="object" required=\{false\}>\
  If `headerBackground` is set, the header will render with a solid background, with a 1px solid border on the bottom.\
\
  By default, the header will render with a transparent background, with a 1px faded border on the bottom.\
</ParamField>\
\
<ParamField path="card-background" type="object" required=\{false\}>\
  The background color of cards and code blocks.\
</ParamField>\
\
## Logo configuration\
\
```yaml docs.yml\
logo: \
  href: mydomain.com\
  dark: path/to/logo.png\
  light: path/to/logo.png\
```\
\
<ParamField path="logo.href" type="string" required=\{false\}>\
  Where clicking on the logo links you to.\
</ParamField>\
\
<ParamField path="logo.dark" type="string" required=\{false\}>\
  Path to the image for the dark mode logo. You can exclude this if you don't have dark mode enabled. SVG format is recommended.\
</ParamField>\
\
<ParamField path="logo.light" type="string" required=\{false\}>\
  Path to the image for the light mode logo. You can exclude this if you don't have light mode enabled. SVG format is recommended.\
</ParamField>\
\
## Redirects configuration\
\
```yaml docs.yml\
redirects:\
  - source: "/old-path"\
    destination: "/new-path"\
  - source: "/old-folder/*"\
    destination: "/new-folder/*"\
```\
\
<ParamField path="source" type="string" required=\{true\}>\
  The path that you want to redirect from.\
</ParamField>\
\
<ParamField path="destination" type="string" required=\{true\}>\
  The path that you want to redirect to.\
</ParamField>\
\
<ParamField path="permanent" type="boolean" required=\{false\}>\
  Toggle between **permanent** and **temporary** redirect (default `false`). When true, the status code is 308. When false the status code is 307.\
</ParamField>\
\
## NavBar links configuration\
\
```yaml docs.yml\
navbar-links:\
  - type: minimal\
    text: Contact support\
    href: https://example.com/support\
  - type: filled\
    text: Login\
    href: https://example.com/login\
    rounded: false\
```\
\
<ParamField path="type" type="enum" required=\{false\}>\
  One of `outlined`, `minimal`, or `filled`. This value controls the styling of the button.\
</ParamField>\
\
<ParamField path="href" type="string" required=\{false\}>\
  The url once you click on the button. Example: [https://buildwithfern.com/contact](https://buildwithfern.com/contact)\
</ParamField>\
\
<ParamField path="text" type="string" required=\{false\}>\
  Text inside the button.\
</ParamField>\
\
<ParamField path="rounded" type="boolean" required=\{false\} default="false">\
  When `true`, the border radius of the button will be fully rounded.\
</ParamField>\
\
<ParamField path="icon" type="string" required=\{false\}>\
  The [Font Awesome icon](https://fontawesome.com/icons) to be used in the button. This icon will appear to the **left** of the text content. Pro and Brand Icons from Font Awesome are supported.\
</ParamField>\
\
<ParamField path="rightIcon" type="string" required=\{false\}>\
  The [Font Awesome icon](https://fontawesome.com/icons) to be used in the button. This icon will appear to the **right** of the text content. Pro and Brand Icons from Font Awesome are supported.\
\
  By default, the `rightIcon` for a `filled` button is set to `arrow-right`.\
</ParamField>\
\
## Background image configuration\
\
```yaml docs.yml\
background-image: \
  light: ./path/to/bg-light.svg\
  dark: ./path/to/bg-dark.svg\
```\
\
<ParamField path="background-image.light" type="string" required=\{false\}>\
  Relative filepath to the light-mode background image.\
</ParamField>\
\
<ParamField path="background-image.dark" type="string" required=\{false\}>\
  Relative filepath to the dark-mode background image.\
</ParamField>\
\
## Typography configuration\
\
```yaml docs.yml \{2-16\}\
typography:\
  bodyFont:\
    name: Inter-Regular\
    path: ./fonts/Inter-Regular.woff2\
  headingsFont:\
    name: Inter-Bold\
    paths: \
      - path: ./fonts/Inter-Bold.woff2\
        weight: "400"\
        style: normal\
      - path: ./fonts/Inter-Bold.woff2\
        weight: 500 900 # <-- indicates a range of weights\
        style: normal    \
  codeFont: \
    name: Roboto-Mono-Regular\
    path: ./fonts/Roboto-Mono-Regular.woff2\
```\
\
<ParamField path="typography.bodyFont" type="object" required=\{false\}>\
  Customize page and section titles. If not supplied, defaults to the body font.\
\
  Learn more about font configuration [here](/learn/docs/getting-started/global-configuration#font-configuration).\
</ParamField>\
\
<ParamField path="typography.headingsFont" type="object" required=\{false\}>\
  Customize paragraph text and other body text.\
\
  Learn more about font configuration [here](/learn/docs/getting-started/global-configuration#font-configuration).\
</ParamField>\
\
<ParamField path="typography.codeFont" type="object" required=\{false\}>\
  Customize code blocks and inline code snippets.\
\
  Learn more about font configuration [here](/learn/docs/getting-started/global-configuration#font-configuration).\
</ParamField>\
\
### Font configuration\
\
<CodeGroup>\
  ```yaml title="Basic" \{3-4\}\
  typography:\
    bodyFont:\
      name: Inter-Regular\
      path: ./fonts/Inter-Regular.woff2\
  ```\
\
  ```yaml title="Variable Font" \{3-10\}\
  typography:\
    bodyFont:\
      name: Inter-Regular\
      paths: \
        - path: ./fonts/Inter-Bold.woff2\
          weight: "400"\
          style: normal\
        - path: ./fonts/Inter-Bold.woff2\
          weight: 500 900 # <-- indicates a range of weights\
          style: normal    \
  ```\
</CodeGroup>\
\
<ParamField path="name" type="string" required=\{false\}>\
  The name of the font. Defaults to a generated name that will be used to reference your custom font in the eventually injected CSS.\
</ParamField>\
\
<ParamField path="path" type="string" required=\{false\}>\
  Relative filepath to a variable font file. If the font file is not variable, use `paths` instead.\
\
  <Note>\
    Supported font file types are `.woff` and `woff2`.\
  </Note>\
</ParamField>\
\
<ParamField path="paths" type="object" required=\{false\}>\
  A list of font files for particular weights. Each element in the list includes a `path`, `weight`, and `style` property.\
</ParamField>\
\
## Layout configuration\
\
```yaml docs.yml\
layout:\
  header-height: 70px\
  page-width: 1344px\
  content-width: 672px\
  sidebar-width: 336px\
  searchbar-placement: header\
  tabs-placement: header\
  content-alignment: left\
```\
\
<ParamField path="layout.header-height" type="string" required=\{false\}>\
  Sets the height of the header. Defaults to `4rem` (`64px`). Valid options are `\{number\}rem` or `\{number\}px`.\
</ParamField>\
\
<ParamField path="layout.page-width" type="string" required=\{false\}>\
  Sets the maximum width of the docs layout, including the sidebar and content. Defaults to `88rem` (`1408px`).\
  Valid options are `\{number\}rem`, `\{number\}px`, or `full`.\
</ParamField>\
\
<ParamField path="layout.content-width" type="string" required=\{false\}>\
  Sets the maximum width of the Markdown article content. Defaults to `44rem` (`704px`).\
  Valid options are `\{number\}rem` or `\{number\}px`.\
</ParamField>\
\
<ParamField path="layout.sidebar-width" type="string" required=\{false\}>\
  Sets the width of the sidebar in desktop mode. Defaults to `18rem` (`288px`). Valid options are `\{number\}rem` or `\{number\}px`.\
</ParamField>\
\
<ParamField path="layout.searchbar-placement" type="string" required=\{false\}>\
  Sets the placement of the searchbar. Can be one of `header`, `sidebar` or `header_tabs` (places the searchbar in the header but on the tabs row).\
  Defaults to `sidebar`.\
\
  <Note>\
    This setting is ignored when \
\
    `disable-header`\
\
     is set to true.\
  </Note>\
</ParamField>\
\
<ParamField path="layout.tabs-placement" type="string" required=\{false\}>\
  Set the placement of the tabs. Can be one of `header` or `sidebar`.\
  Defaults to `sidebar`.\
\
  <Note>\
    This setting is ignored when \
\
    `disable-header`\
\
     is set to true.\
  </Note>\
</ParamField>\
\
<ParamField path="layout.content-alignment" type="string" required=\{false\}>\
  Set the alignment of the Markdown content. Can be one of `center` or `left`.\
  Defaults to `center`.\
</ParamField>\
\
<ParamField path="layout.disable-header" type="boolean" required=\{false\}>\
  If set to true, the header will not be rendered. Instead, the logo will be rendered as part of the sidebar,\
  and a 1px border will separate the sidebar from the content.\
</ParamField>\
\
## GitHub configuration\
\
```yaml docs.yml\
edit-this-page: \
  github: \
    owner: fern\
    repo: plant-store-docs\
    branch: main\
```\
\
<Warning>\
  Be sure the repository is set to **public** visibility.\
</Warning>\
\
<ParamField path="github.owner" type="string" required=\{true\}>\
  The owner of the GitHub repository where you host your documentation.\
</ParamField>\
\
<ParamField path="github.repo" type="string" required=\{true\}>\
  The name of the GitHub repository where you host your documentation.\
</ParamField>\
\
<ParamField path="github.branch" type="string" required=\{true\}>\
  The branch of the repository you would like the GitHub editor to open a PR to. Default is `main`.\
</ParamField>\
\
## Landing page configuration\
\
```yaml docs.yml\
landing-page: \
  page: Page Title\
  path: path/to/landing-page.mdx\
```\
\
<ParamField path="page" type="string" required=\{true\}>\
  The name of the landing page.\
</ParamField>\
\
<ParamField path="path" type="string" required=\{true\}>\
  Relative filepath to the desired landing page Markdown file.\
</ParamField>\
\
See [VapiAI's landing page live](https://docs.vapi.ai/welcome) and the associated [Markdown file](https://github.com/VapiAI/docs/blob/main/fern/welcome.mdx?plain=1).\
\
\
# Project Structure\
\
> An overview of the file and folder structure of a Fern Docs project\
\
This page provides an overview of the file and folder structure of a Fern Docs project. The following structure is recommended for organizing your documentation content, but is customizable to fit your needs.\
\
## Top-level folders\
\
<CodeBlock title="fern/">\
  ```bash\
    fern\
    \uc0\u9500 \u9472  pages\
    \uc0\u9500 \u9472  assets\
    \uc0\u9500 \u9472  docs.yml\
    \uc0\u9500 \u9472  openapi\
    \uc0\u9492 \u9472  fern.config.json\
  ```\
</CodeBlock>\
\
A Fern Docs project has the following top-level folders:\
\
* `pages`: Contains the Markdown (MDX) files that make up your documentation.\
* `assets`: Contains any images or videos used in your documentation.\
* `docs.yml`: The configuration file that defines the navigation, theme, and hosting details of your documentation.\
* `openapi`: Contains the OpenAPI Specification file (if you have an API Reference section in your documentation).\
* `fern.config.json`: The configuration file specifying your organization name and CLI version.\
\
## Pages folder\
\
The `pages` folder contains the Markdown (MDX) files that make up your documentation. Each MDX file represents a page in your documentation.\
\
<CodeBlock title="fern/pages">\
  ```bash\
    pages\
    \uc0\u9500 \u9472  introduction\
    \uc0\u9474   \u9500 \u9472  quickstart.mdx\
    \uc0\u9474   \u9500 \u9472  project-structure.mdx\
    \uc0\u9474   \u9492 \u9472  showcase.mdx\
    \uc0\u9500 \u9472  building-your-docs\
    \uc0\u9474   \u9500 \u9472  navigation\
    \uc0\u9474      \u9500 \u9472  sections.mdx\
    \uc0\u9474      \u9500 \u9472  tabs.mdx\
    \uc0\u9474      \u9492 \u9472  versions.mdx\
    \uc0\u9492 \u9472  \u9492 \u9472  configuration.mdx\
\
  ```\
</CodeBlock>\
\
The `pages` folder is organized into subfolders based on the sections of your documentation. Each subfolder contains the MDX files for the pages in that section.\
\
## Assets folder\
\
The `assets` folder contains any images or videos used in your documentation. You can reference these assets in your MDX files using relative paths.\
\
<CodeBlock title="fern/assets">\
  ```bash\
    assets\
    \uc0\u9500 \u9472  favicon.ico\
    \uc0\u9500 \u9472  product-screenshot.svg\
    \uc0\u9500 \u9472  demo-video.mp4\
    \uc0\u9500 \u9472  logo-dark-mode.png\
    \uc0\u9492 \u9472  logo-light-mode.png\
  ```\
</CodeBlock>\
\
## `docs.yml`\
\
The `docs.yml` file is the configuration file that defines the navigation, theme, and hosting details of your documentation. You can customize the appearance and behavior of your documentation by editing this file.\
\
<CodeBlock title="fern/docs.yml of this website">\
  ```yml\
  instances:\
    - url: fern.docs.buildwithfern.com/learn\
      custom-domain: buildwithfern.com/learn\
\
  navigation:\
    - section: Introduction\
      layout:\
        - page: QuickStart\
          path: pages/introduction/quickstart.mdx\
        - page: Project Structure\
          path: pages/introduction/project-structure.mdx\
        - page: Showcase\
          path: pages/introduction/showcase.mdx\
\
  navbar-links:\
    - type: filled\
      text: Book a demo\
      url: https://buildwithfern.com/contact\
\
  logo:\
    light: ./images/logo-primary.svg\
    dark: ./images/logo-white.svg\
\
  colors:\
    accentPrimary:\
      dark: "#ADFF8C"\
      light: "#209d63"\
\
  favicon: ./images/favicon.ico \
\
  title: Fern's Documentation\
  ```\
</CodeBlock>\
\
## API Definitions\
\
<AccordionGroup>\
  <Accordion title="OpenAPI">\
    The `openapi` folder contains the OpenAPI Specification file for your API Reference section. Fern will read either a YAML or JSON file from this folder to generate the API Reference documentation. If you don't have an API Reference section, you can skip this folder.\
\
    <CodeBlock title="fern/openapi">\
      ```bash\
      openapi\
      \uc0\u9492 \u9472  openapi.yaml # OR openapi.json\
      ```\
    </CodeBlock>\
\
    To see what this looks like in practice, check out [Vellum's Fern configuration](https://github.com/vellum-ai/vellum-client-generator/tree/main/fern/openapi).\
  </Accordion>\
\
  <Accordion title="Fern Definition">\
    The `definition` folder contains the Fern Definition YAML files used to generate the API Reference section. If you don't have an API Reference section, you can skip this folder.\
\
    <CodeBlock title="fern/definition">\
      ```bash\
      definition\
      \uc0\u9500 \u9472  pets.yaml\
      \uc0\u9500 \u9472  owners.yaml\
      \uc0\u9500 \u9472  stores.yaml\
      \uc0\u9492 \u9472  api.yaml\
      ```\
    </CodeBlock>\
\
    To see what this looks like in practice, check out [Pier's Fern configuration](https://github.com/pierdeveloper/pier-fern-def/tree/main/fern/definition).\
  </Accordion>\
\
  <Accordion title="Multiple APIs">\
    If you have multiple APIs, you can organize them into separate folders within the `apis` folder. Each API should have its own API definition. For example:\
\
    <CodeBlock title="fern/apis">\
      ```bash\
      apis\
      \uc0\u9500 \u9472  admin\
      \uc0\u9474   \u9492 \u9472  openapi.json \
      \uc0\u9500 \u9472  user\
      \uc0\u9474   \u9492 \u9472  openapi.yaml\
      ```\
    </CodeBlock>\
\
    To see what this looks like in practice, check out [OctoAI's Fern configuration](https://github.com/octoml/fern-config/tree/main/fern/apis).\
  </Accordion>\
</AccordionGroup>\
\
## `fern.config.json`\
\
The `fern.config.json` file specifies your organization name and the version of the Fern CLI used to generate the documentation. You can customize this file to reflect your organization's details.\
\
<CodeBlock title="fern/fern.config.json">\
  ```json\
  \{\
    "organization": "my-organization",\
    "version": "0.24.0"\
  \}\
  ```\
</CodeBlock>\
\
\
# Preview changes locally\
\
> View and share updates to your documentation\
\
Fern offers two ways to preview changes to your documentation: a [local development environment](#local-development) and [unique preview links](#generate-a-preview-link).\
\
## Local development\
\
Fern allows you to view changes to your documentation in a locally-hosted environment.\
\
<Info>\
  **Prerequisite**\
\
  : Please install Node.js (version 18 or higher) before proceeding.\
</Info>\
\
Follow these steps to install and run the Fern CLI:\
\
**Step 1**: Install the Fern CLI:\
\
<CodeGroup>\
  ```bash npm\
  npm i -g fern-api\
  ```\
\
  ```bash yarn\
  yarn global add fern-api\
  ```\
</CodeGroup>\
\
**Step 2**: Navigate to the docs directory (where the `fern` folder is located) and execute the following command:\
\
```bash\
fern docs dev\
```\
\
A local preview of your documentation will be available at `http://localhost:3000`. The functionality is available offline if you have run local development mode online at least once.\
\
<Note>\
  Some features (e.g. search) are disabled in the local development environment.\
</Note>\
\
### Custom ports\
\
By default, Fern uses port 3000. You can customize the port Fern runs on by using the `--port` flag. For example, to run Fern on port 3002,\
use this command:\
\
```bash\
fern docs dev --port 3333\
```\
\
If you attempt to run Fern on a port that's already in use, it will use the next available port:\
\
## Generate a preview link\
\
Fern allows you to generate a shareable preview link displaying the current state of your docs. Each preview link is appended with a UUID and is not indexed. Currently, these links do not expire (this behavior is subject to change in the future).\
\
**Usage**:\
\
```bash\
fern generate --docs --preview\
```\
\
**Example**:\
\
```bash\
fern generate --docs --preview\
\
[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.\
[docs]: Published docs to https://fern-preview-a1da0157-93ca-4b1f-b310-8dd34fb891ca.docs.buildwithfern.com\
\uc0\u9484 \u9472 \
\uc0\u9474  \u10003   docs.example.com\
\uc0\u9492 \u9472 \
```\
\
\
# Publishing your docs\
\
When you are ready for your docs to be publicly accessible, you can publish them using the Fern CLI.\
\
## Usage\
\
```bash\
fern generate --docs\
```\
\
### Example\
\
```bash\
fern generate --docs\
[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.\
[docs]: \uc0\u10003  All checks passed\
[docs]: Published docs to https://plantstore.docs.buildwithfern.com\
\uc0\u9484 \u9472 \
\uc0\u9474  \u10003   https://plantstore.docs.buildwithfern.com\
\uc0\u9492 \u9472 \
```\
\
### Usage in GitHub Actions\
\
To automate the publishing process, you can use a GitHub Action workflow to publish your docs when a push is made to the `main` branch. [Be sure to add the `FERN_TOKEN` for your organization to the repository](/learn/cli-api/cli-reference/commands#fern-token).\
\
```yaml .github/workflows/publish-docs.yml\
name: Publish Docs\
\
on:\
  push:\
    branches:\
      - main\
\
jobs:\
  run:\
    runs-on: ubuntu-latest\
    if: $\{\{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 \}\}\
    steps:\
      - name: Checkout repository\
        uses: actions/checkout@v4\
\
      - name: Install Fern\
        run: npm install -g fern-api\
\
      - name: Publish Docs\
        env:\
          FERN_TOKEN: $\{\{ secrets.FERN_TOKEN \}\}\
        run: fern generate --docs\
```\
\
## Hosting\
\
When you publish your docs, Fern takes care of hosting them for you. To publish your docs to a custom domain, check out our docs [here](/learn/docs/building-your-docs/custom-domain).\
\
### Self-hosting your docs\
\
<Tip>\
  This feature is available on the Enterprise plan. [Contact us](https://buildwithfern.com/contact) to learn more.\
</Tip>\
\
If you need access to your docs offline or would like to host your docs on your own server, Fern offers that option as well. Self-hosted docs have limited access to certain features (including search).\
\
\
# Configure your site navigation\
\
> Set up the navigation for your documentation site built with Fern Docs using the docs.yml file, including tabs, sections, pages, and more.\
\
## Use `docs.yml`\
\
Every Fern Docs website has a special configuration file called `docs.yml`. Use this file to configure the navigation for your documentation site.\
\
<CodeBlock title="An example docs.yml">\
  ```yaml\
  navigation:\
    - section: Home\
      contents:\
        - page: Introduction\
          path: ./intro.mdx\
        - page: Authentication\
          path: ./auth.mdx\
    - api: API Reference\
  navbar-links:\
    - type: secondary\
      text: Contact support\
      url: https://example.com/support\
    - type: primary\
      text: Login\
      url: https://example.com/login\
  ```\
</CodeBlock>\
\
## Sections, contents, and pages\
\
The navigation organizes your documentation in the left-side nav bar. You can create sections for grouping related content. Each `section` has a name and a list of `contents`. The sections appear in the left-side nav bar in the order that they are listed in `docs.yml`.\
\
In `contents`, list your pages with names and corresponding file paths. The supported file types for pages are `.md` or `.mdx`.\
\
A basic navigation configuration with two sections is shown below. The first section is called `Introduction` and contains a single page called `My Page`. The second section is called **API Reference**. This is a special type of section that's automatically generated by Fern, and you do not need to add any pages to it by hand. For more information, see the [Generate API Reference](/learn/docs/api-references/generate-api-ref) page.\
\
```yaml Example navigation config\
navigation:\
  - section: Introduction\
    contents:\
      - page: My Page\
        path: ./pages/my-page.mdx\
  - api: API Reference\
```\
\
If you want to add another page to an existing section, create an `.md` or `.mdx` file. Then in `docs.yml`, create a new `page` in the `contents` list for that section, providing the path to the `.md` or `.mdx` file you created. Example:\
\
```yaml Example navigation config\
navigation:\
  - section: Introduction\
    contents:\
      - page: My Page\
        path: ./pages/my-page.mdx\
      - page: Another Page\
        path: ./pages/another-page.mdx\
  - api: API Reference\
```\
\
To add another section, add another `section` to the `navigation`. Example:\
\
```yaml Example navigation config with additional section\
navigation:\
  - section: Introduction\
    contents:\
      - page: My Page\
        path: ./pages/my-page.mdx\
  - api: API Reference\
  - section: Help Center\
    contents:\
      - page: Contact Us\
        path: contact-us.mdx\
```\
\
### Hiding content\
\
To hide a page or an entire section of your docs, add `hidden: true`. A hidden page or section will still be discoverable using the exact URL, but it will be excluded from search and will not be indexed.\
\
```yaml Example navigation config with additional section \{7, 10\}\
navigation:\
  - section: Introduction\
    contents:\
      - page: My Page\
        path: ./pages/my-page.mdx\
      - page: Hidden Page\
        hidden: true\
        path: ./pages/my-hidden-page.mdx\
  - section: Hidden Sections\
    hidden: true\
    contents:\
      - page: Another Hidden Page\
        path: ./pages/also-hidden.mdx\
```\
\
## Section overviews\
\
To add an overview page to a section, add a `path` property to the section.\
\
```yaml Example section with an overview \{7\}\
navigation:\
  - section: Introduction\
    contents:\
      - page: My Page\
        path: ./pages/my-page.mdx\
      - section: Guides\
        path: ./pages/guide-overview.mdx\
        contents:\
          - page: Simple Guide\
            path: ./pages/guides/simple.mdx\
          - page: Complex Guide\
            path: ./pages/guides/complex.mdx\
```\
\
## Nested sections\
\
If you'd like a section to toggle into more sections and pages, you can nest sections within sections. Here's an example:\
\
```yaml Example navigation config with nested sections\
navigation:\
  - tab: guides\
    layout:\
      - section: Learn\
        contents:\
          - section: Key Concepts\
            contents:\
              - page: Embeddings\
                path: ./docs/pages/embeddings.mdx\
              - page: Prompt Engineering\
                path: ./docs/pages/prompts.mdx\
          - section: Generation\
            contents:\
              - page: Command Nightly\
                path: ./docs/pages/command.mdx\
              - page: Likelihood\
                path: ./docs/pages/likelihood.mdx\
```\
\
<Frame>\
  ![Result of above docs.yml example](https://fern-image-hosting.s3.amazonaws.com/fern/nested-sections.png)\
</Frame>\
\
## Sidebar icons\
\
For icons to appear next to sections and pages, add the `icon` key. The value should be a valid [Font Awesome icon](https://fontawesome.com/icons) name. Pro and Brand Icons from Font Awesome are supported.\
\
```yaml Example navigation config with icons\
navigation:\
  - section: Home\
    icon: fa-regular fa-home\
    contents:\
      - page: My Page\
        icon: fa-regular fa-file\
        path: ./pages/my-page.mdx\
  - api: API Reference\
    icon: fa-regular fa-puzzle\
```\
\
## Links\
\
You can add a link to an external page within your sidebar navigation with the following configuration:\
\
```yaml title="docs.yml"\
navigation:\
  - section: Home\
    contents:\
      - page: Introduction\
        path: ./intro.mdx\
      - link: Our YouTube Channel\
        href: https://www.youtube.com/\
```\
\
<Frame>\
  <img src="file:5d3d12b5-dadb-4927-87ec-ea39281dda4a" alt="An external link within navigation" />\
</Frame>\
\
## Tabs\
\
Within the navigation, you can add `tabs`. Tabs are used to group sections together. The example below shows tabs for `Help Center`, `API Reference`, and an external link to `Github`. Each tab has a `title` and `icon`. [Browse the icons available](https://fontawesome.com/icons) from Font Awesome. Pro and Brand Icons are supported.\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  tabs: \
    api: \
      display-name: API Reference\
      icon: puzzle\
    help:\
      display-name: Help Center\
      icon: home\
    github:\
      display-name: GitHub\
      icon: brands github\
      href: https://github.com/fern-api/fern\
      \
   navigation: \
    - tab: api\
      layout: \
        - section: Introduction\
            contents: \
              - page: My Page\
                  path: my-page.mdx\
          - api: API Reference   \
    - tab: help\
      layout: \
        - section: Help Center\
          contents: \
            - page: Contact Us\
                path: contact-us.mdx\
    - tab: github\
  ```\
</CodeBlock>\
\
Here's an example of what the Tabs implementation looks like:\
\
<Frame>\
  ![Screenshot showing two vertically stacked tabs labeled API Reference and Help\
  Center](https://fern-image-hosting.s3.amazonaws.com/fern/tabs.png)\
</Frame>\
\
## Versions\
\
If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the `versions`. For more information, check out our [documentation on versioning](/learn/docs/building-your-docs/versioning).\
\
\
# Versioning\
\
> Allow users to navigate between different versions of your docs.\
\
<Frame>\
  ![A dropdown of the available versions](file:fd7c5680-d2f8-410c-9007-d1b0a9432cba)\
</Frame>\
\
Each version of your docs can contain its own distinct tabs, sections, pages, and API references. Versions can share content, as well.\
\
**To add versions to your docs:**\
\
<Steps>\
  ### Define your versions\
\
  Create a `versions` folder inside of your `fern` folder. TO specify the contents of each version, add a `.yml` file to the `versions` folder to define the navigational structure of that version. Make sure to include the `navigation` and `tabs` properties, if applicable.\
\
  ```bash\
  fern/\
    \uc0\u9500 \u9472  fern.config.json\
    \uc0\u9500 \u9472  generators.yml\
    \uc0\u9500 \u9472  docs.yml\
    \uc0\u9500 \u9472  pages/\
      \uc0\u9500 \u9472  ...\
    \uc0\u9492 \u9472  versions/\
      \uc0\u9500 \u9472  v2-1/pages/...\
      \uc0\u9500 \u9472  v2-1.yml\
      \uc0\u9500 \u9472  v2-2/pages/...\
      \uc0\u9492 \u9472  v2-2.yml\
  ```\
\
  <CodeBlocks>\
    <CodeBlock title="versions/v2-1.yml">\
      ```yaml\
      navigation: \
        - section: Introduction\
          contents: \
            - page: My Page\
              path: ./v2-1/pages/my-page.mdx  # relative path to the file\
            - page: Shared Resource\
              path: ../shared-pages/shared-resource.mdx\
        - api: API Reference\
      ```\
    </CodeBlock>\
\
    <CodeBlock title="versions/v2-2.yml">\
      ```yaml\
      tabs: \
        api: \
          title: API Reference\
          icon: puzzle\
        help:\
          title: Help Center\
          icon: home\
          \
       navigation:\
        - tab: api\
           contents:\
              - section: Introduction\
                 contents: \
                    - page: My Page\
                      path: ./v2-2/pages/my-page.mdx # relative path to the file\
                    - page: Shared Resource\
                      path: ../shared-pages/shared-resource.mdx\
              - api: API Reference\
         - tab: help\
            contents: \
               - section: Help Center\
                 contents: \
                    - page: Contact Us\
                       path: contact-us.mdx\
      ```\
    </CodeBlock>\
  </CodeBlocks>\
\
  ### Add your version configuration\
\
  To define a version, in `docs.yml`, add an item to the `versions` list, specifying the `display-name` and `path`.\
\
  ```bash\
  fern/\
    \uc0\u9500 \u9472  fern.config.json\
    \uc0\u9500 \u9472  generators.yml\
    \uc0\u9500 \u9472  docs.yml\
    \uc0\u9492 \u9472  versions/\
      \uc0\u9500 \u9472  ...\
      \uc0\u9500 \u9472  v2-1.yml\
      \uc0\u9492 \u9472  v2-2.yml\
  ```\
\
  <CodeBlock title="docs.yml">\
    ```yaml\
    versions: \
      - display-name: v2.2          # shown in the dropdown\
        path: ./versions/v2-2.yml   # relative path to the version file\
      - display-name: v2.1\
        path: ./versions/v2-1.yml\
    ```\
  </CodeBlock>\
\
  ### Remove extra `navigation` from `docs.yml`\
\
  If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the version-specific `.yml` files.\
</Steps>\
\
\
# Add an announcement banner to your docs\
\
> Prominently highlight new features, updates, or important information\
\
An announcement banner is a great way to draw attention to new features and product launches. When configured, the announcement bar appears at the top of your docs site. After the user dismisses the bar, it will reappear the next time you update the announcement.\
\
```yaml docs.yml\
announcement:\
    message: "\uc0\u55357 \u56960  New feature: Announcements are available! (<a href=\\"https://buildwithfern.com/learn/docs/building-your-docs/announcements\\" target=\\"_blank\\">Learn more</a>) \u55357 \u56960 "\
```\
\
Markdown and HTML is supported in the announcement message. You can include links, images, and other formatting. [Custom css](/learn/docs/building-your-docs/custom-css-global-js#custom-css) can be used to customize the style of the announcement.\
\
Another docs change\
\
\
# Configure links and redirects for your site\
\
> Set up the navigation for your documentation site built with Fern Docs using the docs.yml file\
\
## Redirects\
\
The `redirects` object allows you to redirect traffic from one path to another. You can also use [`regex`](https://www.npmjs.com/package/path-to-regexp) within redirects.\
\
<CodeBlock title="docs.yml">\
  ```yml\
  redirects:\
    - source: "/old-path"\
      destination: "/new-path"\
    - source: "/incorrect/path"\
      destination: "/correct/path"\
    - source: "/old-folder/:slug" # <- using regex\
      destination: "/new-folder/:slug"\
  ```\
</CodeBlock>\
\
By default, the redirects implement temporary (302) redirects. If you would like to implement permanent (301) redirects, you can set `permanent: true`.\
\
<CodeBlock title="docs.yml">\
  ```yml\
  redirects:\
    - source: "/old-subdomain"\
      destination: "/new-subdomain"\
      permanent: true\
  ```\
</CodeBlock>\
\
<Note title="Subpaths">\
  If your docs are hosted on a subpath (like `buildwithfern.com/learn`), be sure to include the subpath in the redirect.\
</Note>\
\
## Links\
\
You can add a link to an external page within your sidebar navigation with the following configuration:\
\
```yaml title="docs.yml"\
navigation: \
  - section: Home\
    contents:\
      - page: Introduction\
        path: ./intro.mdx\
      - link: Our YouTube Channel\
        href: https://www.youtube.com/\
```\
\
<Frame>\
  <img src="file:5d3d12b5-dadb-4927-87ec-ea39281dda4a" alt="An external link within navigation" />\
</Frame>\
\
\
# Customizing slugs within your site\
\
By default, Fern generates the slug of a page based on the navigation structure in the `docs.yml` file.\
\
<AccordionGroup>\
  <Accordion title="Example without tabs">\
    ```yaml docs.yml \{5, 7\}\
    instances:\
      - url: plantstore.docs.buildwithfern.com\
      \
    navigation:\
      - section: Get Started\
        contents: \
          - page: Welcome \
            path: ./docs/pages/welcome.mdx\
    ```\
\
    In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/get-started/welcome`.\
  </Accordion>\
\
  <Accordion title="Example with tabs">\
    ```yaml docs.yml \{5, 13, 15\}\
    instances:\
      - url: plantstore.docs.buildwithfern.com\
      \
    tabs: \
      docs:\
        display-name: Docs\
      reference: \
        display-name: API Reference\
      \
    navigation:\
      - tab: docs\
        layout: \
          - section: Get Started\
            contents: \
              - page: Welcome \
                path: ./docs/pages/welcome.mdx\
    ```\
\
    In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/docs/get-started/welcome`.\
  </Accordion>\
</AccordionGroup>\
\
### Renaming slugs\
\
#### Modify a page or section slug\
\
To modify the slug used for a page or section, you can set the `slug` within the `navigation` object.\
\
```yaml \{3, 6\}\
navigation:\
  - section: Get Started\
    slug: start\
    contents: \
      - page: Welcome \
        slug: intro\
        path: ./docs/pages/welcome.mdx\
```\
\
In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/start/intro`.\
\
#### Modify a tab slug\
\
To modify the slug used for a tab, you can set the `slug` within the `tabs` object.\
\
```yaml \{4\}\
tabs: \
  docs:\
    display-name: Docs\
    slug: guides\
  reference: \
    display-name: API Reference\
  \
navigation:\
  - tab: docs\
    layout: \
      - section: Get Started\
        contents: \
          - page: Welcome \
            path: ./docs/pages/welcome.mdx\
```\
\
In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/guides/get-started/welcome`.\
\
#### Override a page's slug\
\
You can set the exact slug of a page within its frontmatter. [You can read more about the frontmatter configuration here](/learn/docs/content/frontmatter#slug).\
\
```yaml title="docs.yml"\
navigation:\
  - section: Get Started\
    slug: start\
    contents: \
      - page: Quick Start \
        path: ./docs/pages/quick-start.mdx\
```\
\
You can set the slug in the frontmatter of `./docs/pages/quick-start.mdx` to `start-up`:\
\
```markdown title="quick-start.mdx" \{2\}\
---\
slug: start-up\
---\
```\
\
The page then becomes available at `plantstore.docs.buildwithfern.com/start-up`.\
\
#### Renaming slugs for subheadings\
\
By default, deep links to subheadings are generated by appending a `#` and the subheading title (converted to `kebab-casing-convention`) onto the page URl.\
\
```yaml docs.yml\
navigation:\
  - section: Get Started\
    contents: \
      - page: Welcome \
        path: ./docs/pages/welcome.mdx\
```\
\
```markdown welcome.mdx\
...\
\
## Frequently Asked Questions \
...\
```\
\
The link to this section will be available at `plantstore.docs.buildwithfern.com/get-started/welcome#frequently-asked-questions`.\
\
To rename the slug of the subheading, add the desired slug\
\
```markdown welcome.mdx\
## Frequently Asked Questions [#faqs]\
```\
\
The link to this section will now be available at `plantstore.docs.buildwithfern.com/get-started/welcome#faqs`.\
\
### Skipping slugs\
\
To ignore a tab or section when generating the slug, simply indicate `skip-slug: true`.\
\
<AccordionGroup>\
  <Accordion title="Example without tabs">\
    ```yaml docs.yml \{6\}\
    instances:\
      - url: plantstore.docs.buildwithfern.com\
      \
    navigation:\
      - section: Get Started\
        skip-slug: true\
        contents: \
          - page: Welcome \
            path: ./docs/pages/welcome.mdx\
    ```\
\
    In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/welcome`.\
  </Accordion>\
\
  <Accordion title="Example with tabs">\
    ```yaml docs.yml \{7, 15\}\
    instances:\
      - url: plantstore.docs.buildwithfern.com\
      \
    tabs: \
      docs:\
        display-name: Docs\
        skip-slug: true\
      reference: \
        display-name: API Reference\
      \
    navigation:\
      - tab: docs\
        layout: \
          - section: Get Started\
            skip-slug: true\
            contents: \
              - page: Welcome \
                path: ./docs/pages/welcome.mdx\
    ```\
\
    In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/welcome`.\
  </Accordion>\
</AccordionGroup>\
\
\
# Hiding content in your site\
\
If you would like to *hide* a section or a page, you can add `hidden: true` to its configuration. Hidden sections and pages are accessible by URL only.\
\
<Tabs>\
  <Tab title="Hidden page">\
    ```yaml title="docs.yml"\
    navigation: \
      - section: Introduction\
        contents: \
          - page: My Page\
            path: ./pages/my-page.mdx\
          - page: Hide and Seek\
            hidden: true\
            path: ./pages/hide-and-seek.mdx\
      - api: API Reference\
    ```\
\
    <Frame>\
      <img src="file:13722c27-9238-4f40-945d-817c34af9526" alt="A site with a hidden page" />\
    </Frame>\
  </Tab>\
\
  <Tab title="Hidden section">\
    ```yaml title="docs.yml"\
    navigation: \
      - section: Introduction\
        contents: \
          - page: My Page\
            path: ./pages/my-page.mdx\
      - api: API Reference\
      - section: Hidden Section\
        hidden: true\
        contents: \
          - page: Hide and Seek\
            path: ./pages/hide-and-seek.mdx\
    ```\
\
    <Frame>\
      <img src="file:ae48608d-691b-4f10-8a7a-9f190025bf8f" alt="A site with a hidden section" />\
    </Frame>\
  </Tab>\
</Tabs>\
\
\
# Fully customize your docs\
\
> Add brand-specific styling, user interactions. and components to make your docs your own.\
\
<Note>\
  Custom CSS & JS are available on the Basic plan.\
  Adding Custom Components is available on the Pro plan.\
</Note>\
\
## Custom CSS\
\
You can add custom CSS to your docs to further customize the look and feel. The defined class names are applied across all MDX files.\
\
Here's an example of what you can do with custom CSS:\
\
<CodeBlock title="styles.css">\
  ```css maxLines=10\
\
  .petstore-table \{\
      background-color: white;\
      border: 1px solid #DEDEE1;\
      border-radius: 4px;\
  \}\
\
  .dark .petstore-table \{ \
      background-color: #1e1e1e;\
      border: 1px solid #2e2e2e;\
  \}\
\
  .petstore-table thead \{\
      position: sticky;\
      top: 0;\
  \}\
\
  .petstore-table thead tr \{\
      background-color: #edecee;\
      border: 1px solid #DEDEE1;\
      border-radius: 4px 4px 0px 0px;\
  \}\
\
  .dark .petstore-table thead tr \{\
      background-color: #2e2e2e;\
      border: 1px solid #2e2e2e;\
  \}\
\
  .petstore-table th \{\
      padding: 6px;\
  \}\
\
  .petstore-table tbody td \{\
      padding: 6px;\
  \}\
\
  .petstore-table tbody tr:nth-child(odd) \{\
      border: 1px solid #DEDEE1;\
  \}\
  .petstore-table tbody tr:nth-child(even) \{\
      border: 1px solid #DEDEE1;\
      background-color: #f7f6f8;\
  \}\
\
  .dark .petstore-table tbody tr:nth-child(odd) \{\
      border: 1px solid #2e2e2e;\
  \}\
\
  .dark .petstore-table tbody tr:nth-child(even) \{\
      border: 1px solid #2e2e2e;\
      background-color: #2e2e2e;\
  \}\
  ```\
</CodeBlock>\
\
<Steps>\
  ### Create `styles.css`\
\
  Add a `styles.css` file and include it in your `fern/` project:\
\
  <CodeBlock title="Add the styles.css file">\
    ```bash \{5\}\
      fern/\
      \uc0\u9500 \u9472  openapi/\
      \uc0\u9500 \u9472  pages/\
      \uc0\u9500 \u9472  images/\
      \uc0\u9500 \u9472  styles.css\
      \uc0\u9500 \u9472  docs.yml\
      \uc0\u9492 \u9472  fern.config.json\
    ```\
  </CodeBlock>\
\
  ### Edit `docs.yml`\
\
  In `docs.yml`, specify the path to the `styles.css` file:\
\
  <CodeBlock title="docs.yml">\
    ```yaml\
    css: ./styles.css\
    ```\
  </CodeBlock>\
\
  ### Add multiple custom CSS files (optional)\
\
  You can specify any number of custom CSS files:\
\
  <CodeBlock title="docs.yml">\
    ```yaml\
    css:\
      - ./css/header-styles.css\
      - ./css/footer-styles.css\
    ```\
  </CodeBlock>\
</Steps>\
\
<Note>\
  For customizing the background, logo, font, and layout of your Docs via Fern's built-in styling,\
  check out the [Global Configuration](/learn/docs/getting-started/global-configuration).\
</Note>\
\
## Custom JavaScript\
\
Customize the behavior of your Docs site by injecting custom JavaScript globally. Add a `custom.js` file and include it in your `fern/` project:\
\
<CodeBlock title="Add the custom.js file">\
  ```bash \{5\}\
    fern/\
    \uc0\u9500 \u9472  openapi/\
    \uc0\u9500 \u9472  pages/\
    \uc0\u9500 \u9472  images/\
    \uc0\u9500 \u9472  custom.js\
    \uc0\u9500 \u9472  docs.yml\
    \uc0\u9492 \u9472  fern.config.json\
  ```\
</CodeBlock>\
\
In `docs.yml`, specify the path to the `custom.js` file:\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  js: ./custom.js\
  ```\
</CodeBlock>\
\
You can also specify multiple custom JS files stored locally and remote:\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  js:\
      - path/to/js/file.js\
      - path: path/to/another/js/file.js\
          strategy: beforeInteractive\
      - url: https://example.com/path/to/js/file.js\
  ```\
</CodeBlock>\
\
### Strategy\
\
Optionally, specify the strategy for each custom JavaScript file. Choose from `beforeInteractive`, `afterInteractive` (default), and `lazyOnload`.\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  js:\
      - path: path/to/another/js/file.js\
          strategy: beforeInteractive\
  ```\
</CodeBlock>\
\
## Custom components\
\
You can use custom CSS and JS to replace Fern's default UI components with your own. The `header` and `footer`\
are the most commonly replaced components. You can replace any component in the docs,\
including the sidebar, tabs, search bar, and more.\
\
To implement your own components in Fern Docs, write JavaScript to render your\
custom components in the DOM. Build to CSS and JavaScript files that\
are stored in `fern/` and referenced in `docs.yml`:\
\
<CodeBlocks>\
  <CodeBlock title="fern/">\
    ```bash \{5-7\}\
      fern/\
      \uc0\u9500 \u9472  openapi/\
      \uc0\u9500 \u9472  pages/\
      \uc0\u9500 \u9472  images/\
      \uc0\u9500 \u9472  dist/\
        \uc0\u9492 \u9472  output.css\
        \uc0\u9492 \u9472  output.js\
      \uc0\u9500 \u9472  docs.yml\
      \uc0\u9492 \u9472  fern.config.json\
    ```\
  </CodeBlock>\
\
  <CodeBlock title="docs.yml">\
    ```yaml\
    css: ./dist/output.css\
    js: ./dist/output.js\
    ```\
  </CodeBlock>\
</CodeBlocks>\
\
### Example custom components\
\
See this [GitHub repo](https://github.com/fern-api/docs-custom-js-example)\
and its [generated docs page](https://custom-js-example.docs.buildwithfern.com/get-started/welcome)\
for an example of how to replace the Fern `header` and `footer` with custom React components.\
\
#### Example custom header\
\
<Frame>\
  <img alt="Custom header" src="file:cf30cca8-c944-496f-ab29-0aee08d2c801" />\
</Frame>\
\
```JavaScript\
ReactDOM.render(\
  React.createElement(NavHeader),\
  document.getElementById('fern-header'),\
)\
```\
\
#### Example custom footer\
\
<Frame>\
  <img alt="Custom footer" src="file:95951718-dc21-4a5d-b4c4-b4d3cc431d72" />\
</Frame>\
\
```JavaScript\
ReactDOM.render(\
  React.createElement(NavFooter),\
  document.getElementById('fern-footer'),\
)\
```\
\
### Important notes\
\
* `ReactDOM.render()` may need to be called multiple times to prevent it from unmounting (this side-effect will be removed in the future).\
* `yarn build` or `npm build` must generate files with deterministic names to be referenced in `docs.yml`. The above example uses a [`vite` config](https://github.com/fern-api/docs-custom-js-example/blob/main/custom-app/vite.config.ts) to accomplish this.\
* For your hosted Docs site, you may need to update your CD steps to include building the react-app.\
\
<Info>\
  This approach is subject to change, with notice, as we make improvements to the plugin architecture.\
</Info>\
\
\
# Pull request previews\
\
> Fern's PR previews feature lets you preview changes to your docs from pull requests before merging to the live docs site. Use manually or in GitHub Actions.\
\
`PR previews` offer a way to preview changes from pull requests (PRs) before merging code to a production branch. This is useful for reviewing documentation changes before publishing them to your live documentation site. Use manually or in GitHub Actions.\
\
## Usage\
\
```bash\
fern generate --docs --preview\
```\
\
## Example\
\
```bash\
fern generate --docs --preview\
\
[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings.\
[docs]: Published docs to https://fern-preview-a1da0157-93ca-4b1f-b310-8dd34fb891ca.docs.buildwithfern.com\
\uc0\u9484 \u9472 \
\uc0\u9474  \u10003   docs.example.com\
\uc0\u9492 \u9472 \
```\
\
## Usage in GitHub Actions\
\
The following is a GitHub Action workflow that generates a preview URL for every pull request. [Be sure to add the `FERN_TOKEN` for your organization to the repository](/learn/cli-api/cli-reference/commands#fern-token).\
\
<CodeBlock title=".github/workflows/preview-docs.yml">\
  ```yaml\
  name: preview-docs\
\
  on:\
    pull_request\
\
  jobs:\
      run:\
          runs-on: ubuntu-latest\
          permissions: write-all\
          steps:\
              - name: Checkout repository\
                uses: actions/checkout@v4\
\
              - name: Install Fern\
                run: npm install -g fern-api\
\
              - name: Generate preview URL\
                id: generate-docs\
                env:\
                    FERN_TOKEN: $\{\{ secrets.FERN_TOKEN \}\}\
                run: |\
                    OUTPUT=$(fern generate --docs --preview 2>&1) || true\
                    echo "$OUTPUT"\
                    URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \\K.*(?= \\()')\
                    echo "Preview URL: $URL"\
                    echo "\uc0\u55356 \u57151  Preview your docs: $URL" > preview_url.txt\
\
              - name: Comment URL in PR\
                uses: thollander/actions-comment-pull-request@v2.4.3\
                with:\
                    filePath: preview_url.txt\
  ```\
</CodeBlock>\
\
## Link expiration\
\
Preview links do not expire. However, the time to live (TTL) is subject to change in the future.\
\
\
# Bring your custom domain\
\
> Learn how to set up your Fern-generated documentation site to use a custom subdomain or subpath.\
\
Bring Fern Docs to your custom domain.\
\
You can use:\
\
* A subdomain on your custom domain, such as `docs.example.com`\
* A subpath on your custom domain, such as `example.com/docs`\
\
<Tip>\
  This feature is available on the Basic plan and above. \
\
  [Contact us](https://buildwithfern.com/contact)\
\
   to get set up.\
</Tip>\
\
<AccordionGroup>\
  <Accordion title="Subdomain">\
    To host your documentation on a subdomain, i.e. `docs.mydomain.com`, you need to create a CNAME record in your DNS settings.\
\
    <Steps>\
      ### Update the domain in `docs.yml`\
\
      ```yaml\
      instances:\
       - url: example.docs.buildwithfern.com\
         custom-domain: docs.mydomain.com\
      ```\
\
      Merge your changes into `main`. [Here's an example](https://github.com/octoml/fern-config/blob/389b67679953856ba0716537981a6d749635556f/fern/docs.yml#L1-L3).\
\
      ### Create a CNAME record\
\
      1. Log in to your domain registrar's dashboard.\
      2. Navigate to the DNS settings for your domain.\
      3. Add a new CNAME record with the following details:\
         * **Type**: `CNAME`\
         * **Name**: `docs` (or any subdomain you want to use)\
         * **Value**: `cname.vercel-dns.com.`\
\
      ### Reach out to us\
\
      Once you've completed the steps above, reach out via your dedicated Slack channel or [email](mailto:support@buildwithfern.com).\
\
      You may need to create a TXT record to verify your domain. If you do, we'll provide you with the record to add.\
\
      ### Verify the setup\
\
      Once we've completed the setup on our end, you should be able to access your documentation at `docs.mydomain.com`. SSL will be automatically provisioned for your domain, but it may take a few minutes to propagate globally.\
\
      <Tip>\
        It's helpful to check that you can access your new docs site from a mobile device or incognito browser.\
      </Tip>\
    </Steps>\
  </Accordion>\
\
  <Accordion title="Subpath">\
    To host your documentation on a subpath, i.e. `mydomain.com/docs`, you need to edit your `docs.yml` configuration and then get provider-specific instructions for setting up the subpath. Common providers include Cloudflare, AWS Route53 and Cloudfront, Netlify, and Vercel.\
\
    <Steps>\
      ### Configure the `url` in `docs.yml`\
\
      Append that subpath to the end of the `url`. This example use `docs` for the subpath, but you can use any word you like, such as `reference` or `developer`.\
\
      <CodeBlock title="docs.yml example for subpath">\
        ```yaml\
        instances: \
          - url: example.docs.buildwithfern.com/docs\
        ```\
      </CodeBlock>\
\
      ### Configure the `custom-domain`\
\
      Below the `url`, add a `custom-domain` key as shown in the examples below.\
\
      <CodeBlock title="Custom subpath">\
        ```yaml\
        instances: \
          - url: example.docs.buildwithfern.com/docs\
            custom-domain: example.com/docs\
        ```\
      </CodeBlock>\
\
      [Here's an example.](https://github.com/fern-api/fern/blob/7d8631c6119787a8aaccb4ba49837e73c985db28/fern/docs.yml#L1-L3)\
\
      ### Update the Fern Docs site\
\
      If you created your Fern Docs site using one of our [Docs Quickstarts](/learn/docs/getting-started/quickstart), push the changes you made to your GitHub repository. This runs a GitHub Action to update the site with your new configuration.\
\
      If you need to update your Fern Docs site manually, run `fern generate --docs`.\
\
      ### Reach out to us\
\
      This feature is available on the Fern Docs Basic plan and above. Reach out to [sales@buildwithfern.com](mailto:sales@buildwithfern.com) to set up your subscription and obtain the configuration for setting up your custom subpath.\
    </Steps>\
  </Accordion>\
</AccordionGroup>\
\
\
# Collecting feedback and suggestions from users\
\
Fern offers a variety of ways to track feedback and suggested improvements from users.\
\
## On-page feedback\
\
By default, every Markdown page of your docs contains a feedback component at the bottom of the page:\
\
<Frame>\
  <img src="file:865062fc-b1e7-45d5-83c9-1972455ad61c" />\
</Frame>\
\
<Tip>\
  This feature is available on the Basic plan and above. \
\
  [Contact us](https://buildwithfern.com/contact)\
\
   to get set up.\
</Tip>\
\
The feedback can be sent to you in real-time via the method of your choosing (e.g. Slack, email).\
\
To disable this feature on a page, set `hide-feedback: true` in the frontmatter of that page. You can read more about the frontmatter configuration [here](/learn/docs/content/frontmatter#on-page-feedback).\
\
## Edit this page\
\
Allow users to open directly to the current page in your GitHub repository and suggest changes.\
\
<Frame>\
  <img src="file:87aca2fc-3157-48a9-bcd2-b3ccdf1a35d4" />\
</Frame>\
\
You can configure this feature for the entire site in the [global configuration](/learn/docs/getting-started/global-configuration#instances-configuration), or for an individual page in the [frontmatter of that page](/learn/docs/content/frontmatter#edit-this-page).\
\
\
# Write docs content using Markdown\
\
> Use Markdown and MDX to add content to your Fern documentation site, including Fern's built-in component library.\
\
## Add Markdown or MDX pages\
\
Add pages manually to your documentation by creating Markdown (`.md`) or MDX (`.mdx`) files. New to Markdown? See [Markdown Guide: Getting started](https://www.markdownguide.org/getting-started/).\
\
<Note>\
  NOTE: Throughout our documentation, we refer to both Markdown and MDX as Markdown. [MDX](https://mdxjs.com/) is a version of Markdown, extended to allow the use of JSX components.\
</Note>\
\
Place your pages inside your `fern/` folder and link to them from your [navigation settings](/learn/docs/building-your-docs/navigation) in the `docs.yml` file.\
\
In the example below, the MDX files are inside a folder named `pages/`.\
\
<CodeBlock title="Example folder structure">\
  ```bash\
  fern/\
  \uc0\u9500 \u9472  fern.config.json\
  \uc0\u9500 \u9472  docs.yml\
  \uc0\u9492 \u9472  pages/\
    \uc0\u9500 \u9472  welcome.mdx\
    \uc0\u9492 \u9472  quickstart.mdx\
  ```\
</CodeBlock>\
\
<CodeBlock title="docs.yml">\
  ```yml\
  navigation:\
    - section: Overview\
      contents: \
        - page: Welcome \
          path: ./pages/welcome.mdx\
        - page: Quickstart\
          path: ./pages/quickstart.mdx\
  ```\
</CodeBlock>\
\
## Page header\
\
Fern automatically generates the `<h1>` page header for each page from `docs.yml`. For example, here's the `docs.yml` entry that maps the page you are reading now:\
\
```yml\
          - page: Write Markdown content\
            path: ./docs/pages/fern-docs/content/write-markdown.mdx\
```\
\
The value for `page` is used as the content of the top `<h1>` element of this page. Thus, when adding content to your Markdown pages, begin with `<h2>` instead of `<h1>`.\
\
## Fern components\
\
Fern has a built-in component library you can use in Markdown. [Explore the components.](/learn/docs/content/components/overview)\
\
## Links in Markdown\
\
### Link target\
\
When clicked, links to relative URLs open in the same tab, whereas links to absolute URLs open in a new browser tab.\
\
### Link format\
\
Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows:\
\
<CodeBlock title="Relative link example">\
  ```mdx\
  Read the [Introduction](/learn/overview/introduction).\
  ```\
</CodeBlock>\
\
## Images\
\
You can use locally stored images or URLs to include images in your Markdown pages. Use either [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images-1) or the [`<img>` HTML tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) to insert the image.\
\
## LaTeX\
\
Fern supports [LaTeX](https://www.latex-project.org/) math equations. To use LaTeX, wrap your inline math equations in `$`. For example, `$(x^2 + y^2 = z^2)$` will render $x^2 + y^2 = z^2$.\
\
For display math equations, wrap the equation in `$$`. For example:\
\
```latex\
$$\
% \\f is defined as #1f(#2) using the macro\
\\f\\relax\{x\} = \\int_\{-\\infty\}^\\infty\
    \\f\\hat\\xi\\,e^\{2 \\pi i \\xi x\}\
    \\,d\\xi\
$$\
```\
\
## Diagrams\
\
Fern supports creating diagrams within your Markdown using [Mermaid](https://mermaid.js.org/). Mermaid offers a variety of diagrams, including flowcharts, entity-relationship models, and Gantt charts. To include a Mermaid diagram in your Markdown file, create a codeblock marked with `mermaid`.\
\
````markdown\
```mermaid\
erDiagram\
    CUSTOMER ||--o\{ PLANT-ORDER : places\
    PLANT-ORDER ||--|\{ PLANT-ID : contains\
    CUSTOMER \}|..|\{ DELIVERY-ADDRESS : uses\
```\
````\
\
```mermaid\
erDiagram\
    CUSTOMER ||--o\{ PLANT-ORDER : places\
    PLANT-ORDER ||--|\{ PLANT-ID : contains\
    CUSTOMER \}|..|\{ DELIVERY-ADDRESS : uses\
```\
\
\
# Components Overview\
\
> Enhance your docs with Fern's built-in component library. Use components to create interactive and engaging documentation.\
\
Fern provides a library of 15+ built-in-components to make your documentation more interactive and engaging. Components are building blocks that you can add to any MDX page.\
\
## Usage\
\
Specify a component in your MDX file while writing content. For example, to add a `Card` component, use the following syntax:\
\
```mdx\
<Card \
    title='Open Source' \
    icon='brands github' \
    href='https://github.com/fern-api/fern'\
>\
  Give us a star! Fern's CLI & docs source code is available on GitHub. \
</Card>\
```\
\
This will automatically render a card with the title, icon, and content you specified.\
\
<Card title="Open Source" icon="brands github" href="https://github.com/fern-api/fern">\
  Give us a star! The source code to Fern's CLI is available on GitHub.\
</Card>\
\
## Bring your own components\
\
Want to bring your own UI components, such as a custom header and footer? You can on the Enterprise plan. [Contact us](https://buildwithfern.com/contact) to learn more.\
\
## Requests for new components\
\
Have a component in mind that you'd like to see in Fern? Let us know by filing a [GitHub Issue](https://github.com/fern-api/fern/issues/new?assignees=\\&labels=\\&projects=\\&template=feature-request.md\\&title=%5BFeature%5D).\
\
\
# Accordions\
\
> Expand or collapse to reveal more information\
\
<Accordion title="Single Accordion">\
  Standalone content\
</Accordion>\
\
<Aside>\
  <CodeBlock title="Markdown">\
    ```jsx\
    <Accordion title='Single Accordion'>\
      Standalone content\
    </Accordion>\
    ```\
  </CodeBlock>\
</Aside>\
\
\
# Accordion Groups\
\
> Display expandable/collapsible options that can reveal more information\
\
<AccordionGroup>\
  <Accordion title="Option 1">\
    You can put other components inside Accordions.\
\
    ```ts index.ts\
    export function generateRandomNumber() \{\
      return Math.random();\
    \}   \
    ```\
  </Accordion>\
\
  <Accordion title="Option 2">\
    This is a second option.\
  </Accordion>\
\
  <Accordion title="Option 3">\
    This is a third option.\
  </Accordion>\
</AccordionGroup>\
\
<Aside>\
  <CodeBlock title="Markdown">\
    ````jsx\
    <AccordionGroup>\
      <Accordion title="Option 1">\
        You can put other components inside Accordions.\
\
        ```ts\
        export function generateRandomNumber() \{\
          return Math.random();\
        \}   \
        ```\
\
      </Accordion>\
\
      <Accordion title="Option 2">\
        This is a second option.\
      </Accordion>\
      \
      <Accordion title="Option 3">\
        This is a third option.\
      </Accordion>\
    </AccordionGroup>\
    ````\
  </CodeBlock>\
</Aside>\
\
\
# Aside\
\
> Push any content inside the Aside component to the right of the page in a sticky container\
\
<CodeBlock title="Markdown">\
  ```jsx\
  <Aside>\
  <EndpointRequestSnippet endpoint='POST /snippets' />\
  </Aside>\
  ```\
</CodeBlock>\
\
<Aside>\
  <EndpointRequestSnippet endpoint="POST /snippets" />\
</Aside>\
\
\
# Callouts\
\
> A built-in component to show important information to the reader\
\
## Callout properties\
\
Customize your Callouts using the `title` and `icon` properties.\
\
<ParamField path="title" type="string" required=\{false\}>\
  The title of your Callout\
</ParamField>\
\
<ParamField path="icon" type="string | element" required=\{false\}>\
  The icon of your Callout. Can be a [Font Awesome](https://fontawesome.com/icons) icon name or an HTML element.\
</ParamField>\
\
<br />\
\
<Tabs>\
  <Tab title="Callout">\
    <Tip title="Example Callout" icon="leaf">\
      This Callout uses a title and a custom icon.\
    </Tip>\
  </Tab>\
\
  <Tab title="Markdown">\
    ```markdown\
    <Tip title="Example Callout" icon="leaf">\
    This Callout uses a title and a custom icon. \
    </Tip>\
    ```\
  </Tab>\
</Tabs>\
\
## Callout varieties\
\
### Note callouts\
\
<Note>\
  This adds a note in the content\
</Note>\
\
```jsx\
<Note>This adds a note in the content</Note>\
```\
\
### Warning callouts\
\
<Warning>\
  This raises a warning to watch out for\
</Warning>\
\
```jsx\
<Warning>This raises a warning to watch out for</Warning>\
```\
\
### Error callouts\
\
<Error>\
  This indicates a potential error\
</Error>\
\
```jsx\
<Error>This indicates a potential error</Error>\
```\
\
### Info callouts\
\
<Info>\
  This draws attention to important information\
</Info>\
\
```jsx\
<Info>This draws attention to important information</Info>\
```\
\
### Tip callouts\
\
<Tip>\
  This suggests a helpful tip\
</Tip>\
\
```jsx\
<Tip>This suggests a helpful tip</Tip>\
```\
\
### Check callouts\
\
<Check>\
  This brings us a checked status\
</Check>\
\
```jsx\
<Check>This brings us a checked status</Check>\
```\
\
\
# Cards\
\
> Use cards to display content in a box\
\
### Basic\
\
<Card title="Python" icon="brands python" href="https://github.com/fern-api/fern/tree/main/generators/python">\
  The icon field references a Font Awesome icon.\
</Card>\
\
### Custom icon\
\
<Card title="Python" icon=\{<img src="https://upload.wikimedia.org/wikipedia/commons/c/c3/Python-logo-notext.svg" alt="Python logo"/>\} href="https://github.com/fern-api/fern/tree/main/generators/python">\
  Pass in an image tag to use a custom icon.\
</Card>\
\
<Aside>\
  <CodeBlocks>\
    <CodeBlock title="Basic">\
      ```jsx\
      <Card \
          title='Python' \
          icon='brands python' \
          href='https://github.com/fern-api/fern/tree/main/generators/python'\
      >\
      View Fern's Python SDK generator.\
      </Card>\
      ```\
    </CodeBlock>\
\
    <CodeBlock title="Custom Icon">\
      ```jsx\
      <Card \
          title='Python' \
          icon=\{<img src="https://upload.wikimedia.org/wikipedia/commons/c/c3/Python-logo-notext.svg" alt="Python logo"/>\} \
          href='https://github.com/fern-api/fern/tree/main/generators/python'\
      >\
      View Fern's Python SDK generator.\
      </Card>\
      ```\
    </CodeBlock>\
  </CodeBlocks>\
</Aside>\
\
\
# Card Groups\
\
> Show cards side by side in a grid format\
\
The `CardGroup` component lets you group multiple `Card` components together. It's most often used to put multiple cards on the same column.\
\
<CardGroup cols=\{2\}>\
  <Card title="First Card" icon="circle-1">\
    This is the first card.\
  </Card>\
\
  <Card title="Second Card" icon="circle-2">\
    This is the second card.\
  </Card>\
\
  <Card title="Third Card" icon="circle-3">\
    This is the third card.\
  </Card>\
\
  <Card title="Fourth Card" icon="circle-4">\
    This is the fourth and final card.\
  </Card>\
</CardGroup>\
\
<Aside>\
  <CodeBlock title="Markdown">\
    ```jsx\
    <CardGroup cols=\{2\}>\
      <Card title="First Card" icon="circle-1">\
        This is the first card.\
      </Card>\
      <Card title="Second Card" icon="circle-2">\
        This is the second card.\
      </Card>\
      <Card title="Third Card" icon="circle-3">\
        This is the third card.\
      </Card>\
      <Card title="Fourth Card" icon="circle-4">\
        This is the fourth and final card.\
      </Card>\
    </CardGroup>\
    ```\
  </CodeBlock>\
</Aside>\
\
\
# Code Blocks\
\
> Write beautiful code snippets in your documentation\
\
Fern uses [Shiki](https://shiki.matsu.io/) to do syntax highlighting.\
It's very reliable and performant. Below are examples of how you can configure syntax highlighting in code snippets.\
\
## Basic\
\
To create a code snippet, you need to wrap your code in three backticks.\
You can also specify the language for syntax highlighting after the opening backticks.\
\
<Tabs>\
  <Tab title="Example">\
    ```js\
    console.log("hello world")\
    ```\
  </Tab>\
\
  <Tab title="Markdown">\
    ````mdx\
    ```js\
    console.log("hello world")\
    ```\
    ````\
  </Tab>\
</Tabs>\
\
## Titles\
\
You can add a title to your code snippet by adding a title after the language identifier.\
\
<Tabs>\
  <Tab title="Example">\
    ```js Hello World Snippet\
    console.log("hello world")\
    ```\
  </Tab>\
\
  <Tab title="Markdown">\
    ````mdx\
    ```js Hello World Snippet\
    console.log("hello world")\
    ```\
    ````\
\
    <Note>\
      You may also use a `title` prop or `filename` prop to achieve the same result.\
\
      For example, `title="Hello World Snippet"` or `filename="Hello World Snippet"`.\
    </Note>\
  </Tab>\
</Tabs>\
\
## Line highlighting\
\
You can highlight specific lines in your code snippet by adding a comment `[!code highlight]` or by\
placing a numeric range inside `\{\}` after the language identifier.\
\
<Tabs>\
  <Tab title="Example">\
    ```js \{2-4\}\
    console.log("Line 1");\
    console.log("Line 2");\
    console.log("Line 3");\
    console.log("Line 4");\
    console.log("Line 5");\
    ```\
  </Tab>\
\
  <Tab title="Markdown (Using Comments)">\
    ````markdown\
    ```javascript\
    console.log("Line 1");\
    console.log("Line 2"); // [!code highlight]\
    console.log("Line 3"); // [!code highlight]\
    console.log("Line 4"); // [!code highlight]\
    console.log("Line 5");\
    ```\
    ````\
  </Tab>\
\
  <Tab title="Markdown (Using Attribute)">\
    ````markdown\
    ```javascript \{2-4\}\
    console.log("Line 1");\
    console.log("Line 2");\
    console.log("Line 3");\
    console.log("Line 4");\
    console.log("Line 5");\
    ```\
    ````\
\
    <Note>\
      The range is inclusive and can be a single number, a comma-separated list of numbers, or ranges.\
\
      For example, `\{1,3,5-7\}` will highlight lines 1, 3, 5, 6, and 7.\
    </Note>\
  </Tab>\
</Tabs>\
\
## Line focusing\
\
Instead of highlighting lines, you can focus on specific lines by adding a comment `[!code focus]` or by adding a\
`focus` attribute after the language identifier. The `focus` attribute works the same way as the `highlight` attribute.\
\
<Tabs>\
  <Tab title="Example">\
    ```javascript focus=\{2-4\}\
    console.log("Line 1");\
    console.log("Line 2");\
    console.log("Line 3");\
    console.log("Line 4");\
    console.log("Line 5");\
    ```\
  </Tab>\
\
  <Tab title="Markdown">\
    ````markdown\
    ```javascript focus=\{2-4\}\
    console.log("Line 1");\
    console.log("Line 2");\
    console.log("Line 3");\
    console.log("Line 4");\
    console.log("Line 5");\
    ```\
    ````\
  </Tab>\
</Tabs>\
\
## Max height\
\
You can control the max height of the code block by adding\
a `maxLines` attribute after the language identifier. The\
`maxLines` attribute should be a number representing the maximum\
number of lines to display. By default, the code block will display up to 20 lines.\
\
<Tabs>\
  <Tab title="Example">\
    ```python maxLines=10\
    def is_prime(num):\
        """Check if a number is prime."""\
        if num <= 1:\
            return False\
        for i in range(2, num):\
            if num % i == 0:\
                return False\
        return True\
\
    start = 10\
    end = 50\
\
    print(f"Prime numbers between \{start\} and \{end\} are:")\
\
    prime_numbers = []\
\
    for num in range(start, end+1):\
        if is_prime(num):\
            prime_numbers.append(num)\
\
    for prime in prime_numbers:\
        print(prime)\
    ```\
  </Tab>\
\
  <Tab title="Markdown">\
    ````markdown maxLines=10\
    ```python maxLines=10\
    def is_prime(num):\
        """Check if a number is prime."""\
        if num <= 1:\
            return False\
        for i in range(2, num):\
            if num % i == 0:\
                return False\
        return True\
\
    start = 10\
    end = 50\
\
    print(f"Prime numbers between \{start\} and \{end\} are:")\
\
    prime_numbers = []\
\
    for num in range(start, end+1):\
        if is_prime(num):\
            prime_numbers.append(num)\
\
    for prime in prime_numbers:\
        print(prime)\
    ```\
    ````\
\
    <Note>\
      To disable the default 20 lines limit, you can set `maxLines` to `0`.\
    </Note>\
  </Tab>\
</Tabs>\
\
## Wrap overflow\
\
By default, long lines that exceed the width of the code block become scrollable:\
\
```txt title="Without Word Wrap"\
A very very very long line of text that may cause the codeblock to overflow and scroll as a result. \
```\
\
To disable scrolling and wrap overflow onto the next line, use the `wordWrap` prop:\
\
```txt title="With Word Wrap" wordWrap\
A very very very long line of text that may cause the codeblock to overflow and scroll as a result. \
```\
\
## Combining props\
\
You can combine the `title`, `highlight`, `focus`, `maxLines`, and `wordWrap`\
props to create a code block with a title, highlighted lines,\
and a maximum height.\
\
<Tabs>\
  <Tab title="Example">\
    ```javascript title="Hello, World!" \{2-4\} maxLines=5\
    console.log("Line 1");\
    console.log("Line 2");\
    console.log("Line 3");\
    console.log("Line 4");\
    console.log("Line 5");\
    console.log("Line 6");\
    console.log("Line 7");\
    console.log("Line 8");\
    console.log("Line 9");\
    console.log("Line 10");\
    ```\
  </Tab>\
\
  <Tab title="Markdown">\
    ````markdown maxLines=5\
    ```javascript title="Hello, World!" \{2-4\} maxLines=5\
    console.log("Line 1");\
    console.log("Line 2");\
    console.log("Line 3");\
    console.log("Line 4");\
    console.log("Line 5");\
    console.log("Line 6");\
    console.log("Line 7");\
    console.log("Line 8");\
    console.log("Line 9");\
    console.log("Line 10");\
    ```\
    ````\
  </Tab>\
</Tabs>\
\
## Tabbed CodeBlocks\
\
The `CodeBlocks` component is used to display multiple code snippets in a tabbed view. It does not take any props.\
\
<Tabs>\
  <Tab title="Example">\
    <CodeBlocks>\
      ```javascript title="helloWorld.js"\
      console.log("Hello World");\
      ```\
\
      ```python title="hello_world.py"\
      print('Hello World!')\
      ```\
\
      ```java title="HelloWorld.java"\
      class HelloWorld \{\
          public static void main(String[] args) \{\
              System.out.println("Hello, World!");\
          \}\
      \}\
      ```\
    </CodeBlocks>\
  </Tab>\
\
  <Tab title="Markdown">\
    ````jsx maxLines=0\
    <CodeBlocks>\
    ```javascript title="helloWorld.js"\
    console.log("Hello World");\
    ```\
\
    ```python title="hello_world.py"\
    print('Hello World!')\
    ```\
\
    ```java title="HelloWorld.java"\
        class HelloWorld \{\
            public static void main(String[] args) \{\
                System.out.println("Hello, World!");\
            \}\
        \}\
    ```\
    </CodeBlocks>\
    ````\
  </Tab>\
</Tabs>\
\
\
# Steps\
\
> The Steps component helps you display a set of instructions to the user.\
\
The `Steps` component is used when you want to display a set of instructions for the user to follow.\
\
<Steps>\
  ### First Step\
\
  Initial instructions.\
\
  ### Second Step\
\
  More instructions.\
\
  ### Third Step\
\
  Final Instructions\
</Steps>\
\
<Aside>\
  <CodeBlock title="Markdown">\
    ```jsx Steps Example\
    <Steps>\
      ### First Step\
        Initial instructions.\
\
      ### Second Step\
        More instructions.\
      \
      ### Third Step\
        Final Instructions\
    </Steps>\
    ```\
  </CodeBlock>\
</Aside>\
\
\
# Frames\
\
> Wrap images in a container with the frame component\
\
<Frame caption="Beautiful mountains">\
  <img src="https://images.pexels.com/photos/1867601/pexels-photo-1867601.jpeg" alt="Sample photo of mountains" />\
</Frame>\
\
<Aside>\
  <CodeBlock title="Default">\
    ```jsx title="Default"\
      <Frame\
        caption="Beautiful mountains"\
      >\
          <img src="https://images.pexels.com/photos/1867601.jpeg" alt="Sample photo of mountains" />\
      </Frame>\
    ```\
  </CodeBlock>\
</Aside>\
\
### Adding a subtle background\
\
In the scenario where you want to draw more attention to your framed images or your content blends with the main background of your documentation, you can use the `background="subtle"` prop to add a subtle background to the frame.\
\
<Frame caption="Beautiful mountains" background="subtle">\
  <img src="https://images.pexels.com/photos/1867601/pexels-photo-1867601.jpeg" />\
</Frame>\
\
```jsx title="Subtle background" \{3\}\
  <Frame\
    caption="Beautiful mountains"\
    background="subtle"\
  >\
      <img src="./relative/path/to/photo.jpeg" />\
  </Frame>\
```\
\
\
# Tabs\
\
> The Tabs component allows you to display related content in a tabbed view.\
\
You can add any number of tabs.\
\
<Tabs>\
  <Tab title="First Tab">\
    \uc0\u9757 \u65039  Welcome to the content that you can only see inside the first Tab.\
  </Tab>\
\
  <Tab title="Second Tab">\
    \uc0\u9996 \u65039  Here's content that's only inside the second Tab.\
  </Tab>\
\
  <Tab title="Third Tab">\
    \uc0\u55357 \u56490  Here's content that's only inside the third Tab.\
  </Tab>\
</Tabs>\
\
<Aside>\
  <CodeBlock title="Markdown">\
    ```jsx\
    <Tabs>\
      <Tab title="First Tab">\
        \uc0\u9757 \u65039  Welcome to the content that you can only see inside the first Tab.\
      </Tab>\
      <Tab title="Second Tab">\
        \uc0\u9996 \u65039  Here's content that's only inside the second Tab.\
      </Tab>\
      <Tab title="Third Tab">\
        \uc0\u55357 \u56490  Here's content that's only inside the third Tab.\
      </Tab>\
    </Tabs>\
    ```\
  </CodeBlock>\
</Aside>\
\
\
# Endpoint Request Snippet\
\
> Reference an endpoint request from your API Reference\
\
The `EndpointRequestSnippet` component is used to reference an endpoint request from\
your API Reference. Below is an example of referencing the request for the `POST /snippets` endpoint.\
\
<CodeBlock title="Markdown">\
  ```jsx\
  <EndpointRequestSnippet endpoint="POST /snippets" />\
  ```\
</CodeBlock>\
\
will be rendered as:\
\
<EndpointRequestSnippet endpoint="POST /snippets" />\
\
### Reference particular examples\
\
If you want to reference a particular example in the request snippet, you can set `example` prop\
to the name of the example. See the steps below:\
\
<Steps>\
  ### Define named examples\
\
  The highlighted lines show how to set the example name.\
\
  <AccordionGroup>\
    <Accordion title="OpenAPI">\
      ```yaml \{12\}\
      paths:\
        /pet:\
          put:\
            summary: Update an existing pet \
            operationId: pets_update\
            requestBody: \
              content:\
                application/json:\
                  schema:\
                    $ref: '#/components/schemas/Pet'\
                  examples:\
                    ExampleWithMarkley:\
                      summary: This is an example of a Pet\
                      value: \
                        name: Markley\
                        id: 44\
      ```\
    </Accordion>\
\
    <Accordion title="Fern Definition">\
      ```yaml \{11\}\
      service:\
        auth: true\
        base-path: ""\
        endpoints:\
          update:\
            docs: Update an existing pet \
            method: PUT\
            path: /pet\
            request: Pet\
            examples:\
              - name: ExampleWithMarkley\
                docs: This is an example of a Pet\
                request:\
                  name: Markley\
                  id: 44\
      ```\
    </Accordion>\
  </AccordionGroup>\
\
  ### Reference the example\
\
  In the API Definition, the example had a name `ExampleWithMarkley`. You can reference\
  the example directly:\
\
  ```jsx \{3\}\
    <EndpointRequestSnippet \
      endpoint="PUT /pet" \
      example="ExampleWithMarkley"\
    />\
  ```\
</Steps>\
\
\{/* ### Props\
\
Below is a description of all the supported props for the `EndpointRequestSnippet` component. \
\
```fern\
EndpointRequestSnippetProps:\
  properties:\
    endpoint:\
      type: string\
      docs: The endpoint using `METHOD /path` format.\
    example:\
      type: optional<string>\
      docs: The name of the example to display, defaults to the first example.\
``` */\}\
\
\
# Endpoint Response Snippet\
\
> Reference an endpoint response from your API Reference\
\
The `EndpointResponseSnippet` component is used to reference an endpoint\
response from your API Reference. Below is an example of referencing the\
response for the `POST /snippets` endpoint.\
\
<CodeBlock title="Markdown">\
  ```jsx\
  <EndpointResponseSnippet endpoint='POST /snippets' />\
  ```\
</CodeBlock>\
\
will be rendered as\
\
<EndpointResponseSnippet endpoint="POST /snippets" />\
\
### Reference particular examples\
\
If you want to reference a particular example in the response snippet, you can set `example` prop\
to the name of the example. See the steps below:\
\
<Steps>\
  ### Define named examples\
\
  The highlighted lines show how to set the example name.\
\
  <AccordionGroup>\
    <Accordion title="OpenAPI">\
      ```yaml \{13\}\
      paths:\
        /pet/\{petId\}:\
          put:\
            summary: Get a pet \
            operationId: pets_get\
            responses: \
              '200': \
                content:\
                  application/json:\
                    schema:\
                      $ref: '#/components/schemas/Pet'\
                    examples:\
                      ExampleWithMarkley:\
                        summary: This is an example of a Pet\
                        value: \
                          name: Markley\
                          id: 44\
      ```\
    </Accordion>\
\
    <Accordion title="Fern Definition">\
      ```yaml \{11\}\
      service:\
        auth: true\
        base-path: ""\
        endpoints:\
          update:\
            docs: Get a pet\
            method: GET\
            path: /pet/\{petId\}\
            response: Pet\
            examples:\
              - name: ExampleWithMarkley\
                docs: This is an example of a Pet\
                response:\
                  body: \
                    name: Markley\
                    id: 44\
      ```\
    </Accordion>\
  </AccordionGroup>\
\
  ### Reference the example\
\
  In the API Definition, the example had a name `ExampleWithMarkley`. You can reference\
  the example directly:\
\
  ```jsx \{3\}\
    <EndpointResponseSnippet \
      endpoint="GET /pet/\{petId\}" \
      example="ExampleWithMarkley"\
    />\
  ```\
</Steps>\
\
\{/* ### Props\
\
Below is a description of all the supported props for the `EndpointResponseSnippet` component. \
\
```fern\
EndpointResponseSnippetProps:\
  properties:\
    endpoint:\
      type: string\
      docs: The endpoint using `METHOD /path` format.\
    example:\
      type: optional<string>\
      docs: The name of the example to display, defaults to the first example.\
``` */\}\
\
\
# Customize content using frontmatter\
\
> Use frontmatter to set a variety of page properties and metadata.\
\
You can optionally use frontmatter to set each page's title, full slug override, meta description, a URL to suggest edits to the page, and its OpenGraph image. You can also use frontmatter to disable certain page element like the table of contents and on-page feedback.\
\
Frontmatter must be added to the top of a `.md` or `.mdx` file, before the rest of the content. Use sets of three dashes to indicate the beginning and end of your frontmatter, as shown:\
\
<CodeBlock title="Example frontmatter">\
  ```mdx\
  ---\
  title: Customize content using frontmatter\
  subtitle: Set titles, add meta descriptions, and more \
  slug: frontmatter\
  description: Use frontmatter to set the page title, subtitle, slug, meta description, its OpenGraph image, and a URL to suggest edits.\
  ---\
  ```\
</CodeBlock>\
\
## Title\
\
**Name**: `title`<br />\
**Type**: string<br />\
**Default**: The name of the page as specified in `docs.yml`\
\
Set the content for the [`<title>` element](https://web.dev/learn/html/document-structure#document_title) for a page. This title is displayed in browser tabs, history, and bookmarks, as well as in search engine results. Having a unique and informative title for each page benefits your site's SEO (Search Engine Optimization).\
\
<Tip title="Tip">\
  For more information, see [Google's guidelines for useful\
  titles](https://developers.google.com/search/docs/appearance/title-link#page-titles).\
</Tip>\
\
If no `title` is provided in the frontmatter of a page, Fern uses the value for that page in `docs.yml`.\
\
For example, if a page is defined like this in `docs.yml`:\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  - page: Overview\
    path: ./docs/pages/api-overview.mdx\
  ```\
</CodeBlock>\
\
Then, if Fern does not find a `title` in that page's frontmatter, `Overview` is used for the default title.\
\
### Site-wide title text\
\
You can set a field named `title` in `docs.yml` like this:\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  instances:\
    - url: fern.docs.buildwithfern.com\
\
  title: Fern | Documentation # <-- set site-wide\
  ```\
</CodeBlock>\
\
The value you enter for this field is appended to every page's title across your docs site, as ` - TITLE_VALUE`.\
\
For example, with the above setting in `docs.yml`, the `Overview` page's title becomes `Overview - Fern | Documentation`.\
\
## Subtitle\
\
**Name**: `subtitle`<br />\
**Type**: string<br />\
**Default**: None\
\
Renders as a subtitle on the page. If `description` is not set, `subtitle` is also used as the meta description tag.\
\
## Slug\
\
**Name**: `slug`<br />\
**Type**: string<br />\
**Default**: None\
\
The `slug` you set in a page's frontmatter overrides the URL for that page derived from `docs.yml`. This slug begins from the root of your docs site, ignoring the tab or section that the page is under. This allows you to set a custom full slug for any page.\
\
As an example, consider this navigation setup in `docs.yml`:\
\
<CodeBlock title="docs.yml navigation example">\
  ```yaml\
  navigation:\
    - tab: overview\
      layout:\
        - section: Support\
          contents:\
            - page: Email Us\
              path: ./pages/emailus.mdx\
              slug: email\
  ```\
</CodeBlock>\
\
The `slug` set in `docs.yml` affects only the final part of the URL, so the `emailus.mdx` page is available at `/overview/support/email`.\
\
In contrast, the `slug` that you set in frontmatter affects the full URL. For example, you can set the frontmatter `slug` to `email`, as shown:\
\
<CodeBlock title="frontmatter in emailus.mdx">\
  ```mdx\
  ---\
  slug: email\
  ---\
  ```\
</CodeBlock>\
\
The page then becomes available at `/email`.\
\
## Meta description\
\
**Name**: `description`<br />\
**Type**: string<br />\
**Default**: None\
\
Set the [meta description](https://web.dev/learn/html/metadata#description) for a page. Like the page title, the meta description is important for SEO. It impacts the text that search engines display about your page in search results snippets. It can also influence search engine indexing and ranking. For more information, see [Google's guidelines for meta descriptions](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions).\
\
## Edit this page\
\
**Name**: `edit-this-page-url`<br />\
**Type**: string (absolute URL)<br />\
**Default**: None\
\
Provide the absolute link to the source `.md` or `.mdx` file in GitHub. Fern uses it to add an `Edit this page` link to the page, which users of your documentation can use to suggest corrections or additions.\
\
<Frame>\
  <img src="file:87aca2fc-3157-48a9-bcd2-b3ccdf1a35d4" alt="Edit this page feature" />\
</Frame>\
\
## Meta image\
\
**Name**: `image`<br />\
**Type**: string (absolute URL)<br />\
**Default**: None\
\
Configure the `<meta property="og:image">` metadata for a page using an absolute path to an image hosted online. This provides an image to show next to a link to your documentation when the link is shared on social media, using a metadata protocol called [OpenGraph](https://ogp.me/). For more information, see the [web.dev explanation of OpenGraph](https://web.dev/learn/html/metadata#open_graph).\
\
## Table of contents\
\
**Name**: `hide-toc`<br />\
**Type**: boolean<br />\
**Default**: false\
\
Controls the conditional rendering of the table of contents feature on the right-side of the page. Set to true to disable this feature.\
\
<Frame>\
  <img src="file:e33aab9f-954d-48b7-a67f-7bda3c385b19" alt="Table of contents feature" />\
</Frame>\
\
## Navigation links\
\
**Name**: `hide-nav-links`<br />\
**Type**: boolean<br />\
**Default**: false\
\
Controls the conditional rendering of the navigation links (previous, next) at the bottom of the page. Set to true to disable this feature.\
\
<Frame>\
  <img src="file:354c6886-5c66-47ed-98d8-e02cdec3ef3b" alt="Navigation links feature" />\
</Frame>\
\
## On-page feedback\
\
**Name**: `hide-feedback`<br />\
**Type**: boolean<br />\
**Default**: false\
\
Controls the conditional rendering of the on-page feedback form at the bottom of the page. Set to true to disable this feature.\
\
<Frame>\
  <img src="file:865062fc-b1e7-45d5-83c9-1972455ad61c" alt="On-page feedback feature" />\
</Frame>\
\
## SEO metadata\
\
Fern also supports adding SEO-specific metadata in the frontmatter.\
\
| Property              | Description                                                                                                                                                                                                                                                     | Type                                              |\
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |\
| `headline`            | When set, the `<title />` tag in the document head will use this value rather than the `title` property. This property changes the title that search engines see when crawling this page, and can be used to address Duplicate Title issues in your SEO report. | string                                            |\
| `canonical-url`       | Overrides the canonical url for this page. Must be a full URL including the protocol (i.e. `https://buildwithfern.com/learn/docs/content/frontmatter`)                                                                                                          | string                                            |\
| `og:site_name`        | The name of your website as it should appear when your content is shared.                                                                                                                                                                                       | string                                            |\
| `og:title`            | The title of your page as it should appear when your content is shared.                                                                                                                                                                                         | string                                            |\
| `og:description`      | The description of your page as it should appear when your content is shared.                                                                                                                                                                                   | string                                            |\
| `og:url`              | The URL of your page.                                                                                                                                                                                                                                           | string                                            |\
| `og:image`            | The URL or identifier of the image that will be displayed when your content is shared.                                                                                                                                                                          | URL or relative path to file                      |\
| `og:image:width`      | The width of the image in pixels.                                                                                                                                                                                                                               | number                                            |\
| `og:image:height`     | The height of the image in pixels.                                                                                                                                                                                                                              | number                                            |\
| `og:locale`           | The locale of the page, typically in the format `language_TERRITORY` (e.g., `en_US`).                                                                                                                                                                           | string                                            |\
| `og:logo`             | The URL or identifier of the logo image of your website that will be displayed when your content is shared.                                                                                                                                                     | URL or relative path to file                      |\
| `twitter:title`       | The title of your page as it should appear in a tweet.                                                                                                                                                                                                          | string                                            |\
| `twitter:description` | The description of your page as it should appear in a tweet.                                                                                                                                                                                                    | string                                            |\
| `twitter:handle`      | The Twitter handle of the page creator or site.                                                                                                                                                                                                                 | string                                            |\
| `twitter:image`       | The URL or identifier of the image that will be displayed in a tweet.                                                                                                                                                                                           | URL or relative path to file                      |\
| `twitter:site`        | The name of your website as it should appear in a tweet.                                                                                                                                                                                                        | string                                            |\
| `twitter:url`         | The URL of your page.                                                                                                                                                                                                                                           | string                                            |\
| `twitter:card`        | The type of card to be used for sharing on Twitter.                                                                                                                                                                                                             | `summary`, `summary_large_image`, `app`, `player` |\
| `noindex`             | If set to `true`, the page will not be indexed by search engines. Defaults to `false`.                                                                                                                                                                          | boolean                                           |\
| `nofollow`            | If set to `true`, a search engine will not follow any links present on the page. Defaults to `false`.                                                                                                                                                           | boolean                                           |\
\
\
# Reusable Snippets\
\
> Reusable, custom snippets to keep content in sync. Edit once, update everywhere.\
\
Keep your documentation DRY (Don't Repeat Yourself) by defining a reusable snippet once, and then referencing it in multiple places. This way, you only need to update the snippet in one place to keep all references in sync.\
\
## Create a reusable snippet\
\
To use reusable snippets, start by creating a new folder in your `fern` project called `snippets`. Inside the `snippets` folder, create a new file for each snippet you want to define.\
\
For example:\
\
```bash\
fern\
\uc0\u9492 \u9472  pages\
    \uc0\u9492 \u9472  my-tutorial.mdx\
\uc0\u9492 \u9472  assets\
\uc0\u9492 \u9472  snippets\
    \uc0\u9500 \u9472  herbs.mdx  \
    \uc0\u9500 \u9472  peace-lily.mdx    \
    \uc0\u9492 \u9472  trees.mdx\
```\
\
In each snippet file, define the content you want to reuse. For example, `peace-lily.mdx` might contain:\
\
```mdx snippets/peace-lily.mdx\
<Warning> Remember to water your plant at least twice a week. </Warning>\
```\
\
## Use a reusable snippet\
\
To use a snippet in your documentation, reference it by its file path (including the `.mdx` extension) in your content. For example, to include the `peace-lily` snippet in your content, use:\
\
```mdx pages/my-tutorial.mdx\
---\
title: Getting started with your peace lily\
description: Peace lily care tips for beginners\
---\
\
## Caring for your new plant\
\
Peace lilies are easy to grow and relatively trouble-free.\
\
<Markdown src="../snippets/peace-lily.mdx" />\
```\
\
\
# Keep a Changelog\
\
> Record the notable changes to your project\
\
Keep a record of how your project has changed by writing changelog entries. The changelog will automatically populate with the files contained within the `changelog` folder.\
\
<Frame caption="Keep your users updated as your project evolves" background="subtle">\
  <img src="file:9126a277-bbe7-4abd-bc90-07e5069af537" />\
</Frame>\
\
## Configure your Changelog\
\
<AccordionGroup>\
  <Accordion title="Top-level Changelog">\
    Configure a changelog for your project by creating a changelog folder.\
\
    <CodeBlock title="Configure a Changelog">\
      ```yaml \{4-6\}\
      fern/\
      \uc0\u9500 \u9472  fern.config.json\
      \uc0\u9500 \u9472  docs.yml\
      \uc0\u9500 \u9472  changelog/\
          \uc0\u9500 \u9472  07-08-24.md\
          \uc0\u9492 \u9472  08-21-24.mdx\
      ```\
    </CodeBlock>\
\
    Once you've configured your changelog, specify where it should appear within your docs in your `docs.yml`.\
\
    <CodeBlock title="docs.yml">\
      ```yaml \{8-11\}\
      tabs:\
        guides:\
          display-name: Guides\
          icon: light book-open\
        api:\
          display-name: API Reference\
          icon: light code\
        changelog:\
          display-name: Changelog\
          icon: light clock\
          changelog: ./changelog\
      ```\
    </CodeBlock>\
\
    [View an example](https://github.com/humanloop/humanloop-docs/blob/30ddedaf6d2779361e8ee1f373f722364e5dd71d/fern/versions/v5.yml#L10-L13) in GitHub of Humanloop's `docs.yml` which powers [their Changelog](https://humanloop.com/docs/changelog).\
  </Accordion>\
\
  <Accordion title="API-level Changelog">\
    Configure a changelog at the API-level by creating a changelog folder specific to an API.\
\
    <CodeBlocks>\
      <CodeBlock title="OpenAPI">\
        ```yaml \{6-8\}\
        fern/\
        \uc0\u9500 \u9472  fern.config.json\
        \uc0\u9500 \u9472  docs.yml\
        \uc0\u9492 \u9472  openapi/\
            \uc0\u9500 \u9472  openapi.yml\
            \uc0\u9492 \u9472  changelog/\
                \uc0\u9500 \u9472  07-15-24.md\
                \uc0\u9492 \u9472  08-23-24.mdx\
        ```\
      </CodeBlock>\
\
      <CodeBlock title="Fern Definition">\
        ```yaml \{7-9\}\
        fern/\
        \uc0\u9500 \u9472  fern.config.json\
        \uc0\u9500 \u9472  docs.yml\
        \uc0\u9492 \u9472  definition/\
            \uc0\u9500 \u9472  api.yml\
            \uc0\u9500 \u9472  imdb.yml\
            \uc0\u9492 \u9472  changelog/\
                \uc0\u9500 \u9472  07-15-24.md\
                \uc0\u9492 \u9472  08-23-24.mdx \
        ```\
      </CodeBlock>\
\
      <CodeBlock title="Multiple APIs">\
        ```yaml \{8-10,14-17\}\
        fern/\
        \uc0\u9500 \u9472  fern.config.json\
        \uc0\u9500 \u9472  docs.yml\
        \uc0\u9492 \u9472  apis/\
            \uc0\u9500 \u9472  user-api/\
                \uc0\u9492 \u9472  openapi/\
                    \uc0\u9500 \u9472  openapi.yml\
                    \uc0\u9500 \u9472  openapi-overrides.yml\
                    \uc0\u9492 \u9472  changelog\
                        \uc0\u9500 \u9472  07-15-24.md\
                        \uc0\u9492 \u9472  08-23-24.mdx\
            \uc0\u9492 \u9472  admin-api/\
                \uc0\u9492 \u9472  openapi/\
                    \uc0\u9500 \u9472  openapi.yml\
                    \uc0\u9492 \u9472  changelog\
                        \uc0\u9500 \u9472  06-29-24.md\
                        \uc0\u9492 \u9472  08-02-24.md\
                        \uc0\u9492 \u9472  08-15-24.md\
        ```\
      </CodeBlock>\
    </CodeBlocks>\
\
    Changelogs contained within your API folder will automatically be displayed at the bottom of your API reference. You do not need to configure your changelog(s) within `docs.yml`.\
\
    View an example of a changelog per API in [Astronomer's docs](https://www.astronomer.io/docs/api/iam-api-reference/changelog).\
\
    <Frame caption="A unique changelog per API" background="subtle">\
      <img src="file:91be59ad-6c4b-429c-8e5e-ffca1b81acf9" />\
    </Frame>\
  </Accordion>\
\
  <Accordion title="Section-level Changelog">\
    Configure a changelog for your project by creating a changelog folder.\
\
    <CodeBlock title="Configure a Changelog">\
      ```yaml \{4-6\}\
      fern/\
      \uc0\u9500 \u9472  fern.config.json\
      \uc0\u9500 \u9472  docs.yml\
      \uc0\u9500 \u9472  pages/\
      \uc0\u9500 \u9472  changelog/\
          \uc0\u9500 \u9472  07-08-24.md\
          \uc0\u9492 \u9472  08-21-24.mdx\
      ```\
    </CodeBlock>\
\
    Once you've configured your changelog, specify where it should appear within your navigation in your `docs.yml`.\
\
    <CodeBlock title="docs.yml">\
      ```yaml \{9-11\}\
      navigation:\
        - section: Introduction\
          contents: \
            - page: Authentication\
              path: ./pages/authentication.mdx\
            - page: Versioning\
              path: ./pages/versioning.mdx\
        - api: API Reference\
        - changelog: ./changelog\
          title: Release Notes\
          slug: api-release-notes\
      ```\
    </CodeBlock>\
  </Accordion>\
</AccordionGroup>\
\
## Write a Changelog Entry\
\
Create a new changelog entry by writing a Markdown file. You can use `.md` or `.mdx` files. The benefit of using `.mdx` is that you can leverage the built-in [component library](/learn/docs/content/components/overview) within an entry.\
\
<CodeBlock title="fern/openapi/changelog/2024-07-31.mdx">\
  ```mdx\
  ## Summary\
\
  In the latest release, we've added endpoints to create a new Plant.\
\
  ### What's new?\
\
  New endpoints:\
\
  - `POST /plant` add a new plant to inventory.\
\
  New object schemas:\
\
  - `CreatePlantRequest`\
\
  <Note> Have questions? Reach out to your local botanist. </Note>\
  ```\
</CodeBlock>\
\
### Entry date\
\
Changelog entries are automatically sorted chronologically by the date specific in the file name. Specify the date of your entry using one of the following formats:\
\
* MM-DD-YYYY (e.g., 10-06-2024)\
* MM-DD-YY (e.g., 10-06-24)\
* YYYY-MM-DD (e.g., 2024-04-21)\
\
### Linking to an Entry\
\
Each changelog entry has a unique URL you can direct users to. For example, `https://humanloop.com/docs/v5/changelog/2024/8/16`\
\
\
# Generate your API Reference\
\
> Use Fern Docs to generate your API Reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition.\
\
A key benefit of using Fern Docs is that once you've defined your API, you get your API Reference documentation with just one line.\
Add `- api: API Reference` to your navigation in `docs.yml` and Fern takes care of the rest! You'll see your endpoints, types,\
and cURL snippets automatically populated from your [OpenAPI Specification](/learn/api-definition/openapi/overview) or [Fern Definition](/learn/api-definition/fern/overview).\
\
Example:\
\
```yml docs.yml\
navigation:\
  - api: API Reference\
```\
\
### API Reference configuration options\
\
| Property         | Value                                                                                                  |\
| ---------------- | ------------------------------------------------------------------------------------------------------ |\
| `api` (required) | Title of the API Reference Section                                                                     |\
| `api-name`       | Name of the API we are referencing, if there are [multiple APIs](#include-more-than-one-api-reference) |\
| `audiences`      | List of [audiences](/learn/api-definition/fern/audiences) to filter the API Reference for              |\
| `display-errors` | Displays error schemas in the API References                                                           |\
| `snippets`       | Enable [generated SDK code snippets](/learn/cli-api/api-reference/snippets/get) in your API Reference  |\
| `summary`        | Relative path to the Markdown file; the summary is displayed at the top of the API section             |\
| `layout`         | Customize the order that your API endpoints are displayed in the docs site                             |\
| `icon`           | Icon to display next to the API section in the navigation                                              |\
| `slug`           | Customize the slug for the API section (by default, the slug is generated from the API title)          |\
| `skip-slug`      | When `true`, skips the slug generation for the API section                                             |\
| `alphabetized`   | When `true`, organizes all sections and endpoints in alphabetically order                              |\
| `flattened`      | Display all endpoints at the top level (hides the API Reference Section's title)                       |\
| `paginated`      | Display all endpoints on separate pages (by default, endpoints are displayed on one single, long page) |\
\
More on customizing your API Reference [here](/learn/docs/api-references/customize-api-reference-layout).\
\
### Include more than one API Reference\
\
To include multiple, distinct API definitions in your documentation, you can indicate which to include using the `api-name` property. The `api-name` corresponds to the name of the folder where your API definition is housed.\
\
```yaml title="docs.yml"\
navigation:\
  - api: Plant Store\
    api-name: plant-api\
  - api: Garden\
    api-name: garden-api\
```\
\
\
# Display SDK snippets\
\
> Enable SDK code examples in TypeScript, Python, Go, and more from the request and response examples documented in your API definition. Once enabled, Fern Docs will automatically populate the snippets within your API Reference.\
\
If you use Fern's SDK Generator, you can automatically show SDK code snippets in your API Reference. SDK languages appear in a drop-down. By default, cURL snippets will be displayed to users.\
\
<Frame>\
  ![SDK code snippet selector](https://fern-image-hosting.s3.amazonaws.com/sdk-code-snippets.png)\
</Frame>\
\
## Configuring SDK Snippets\
\
To configure SDK snippets, you'll need to name your SDKs in `generators.yml` and then reference that name in `docs.yml`. In the following example, We'll use `your-organization` as the package name because it is a common practice. For example, Stripe calls their npm package `stripe` and Twilio calls their PyPI package `twilio`.\
\
### Add examples to your API definition\
\
In order to generate code snippets, Fern needs to read request examples from your API definition. If you're using a Fern Definition, you can follow [these instructions](/learn/api-definition/fern/examples). If you're using an OpenAPI Specification, you can follow [these instructions](https://swagger.io/docs/specification/adding-examples/).\
\
### Define a package name for your SDK(s)\
\
<CodeBlock title="generators.yml">\
  ```yaml\
  groups:\
    production:\
      generators:\
        - name: fernapi/fern-python-sdk\
          version: 2.8.0\
          output:\
            location: pypi\
            token: $\{PYPI_TOKEN\}\
            package-name: your-package-name # <--- add this field\
          ...\
       - name: fernapi/fern-typescript-node-sdk\
          version: 0.20.9\
          output:\
            location: npm\
            token: $\{NPM_TOKEN\}\
            package-name: your-package-name # <--- add this field\
       - name: fernapi/fern-ruby-sdk\
          version: 0.6.3\
          output:\
            location: rubygems\
            token: $\{RUBYGEMS_TOKEN\}\
            package-name: your-package-name # <--- add this field\
       - name: fernapi/fern-go-sdk\
          version: 0.22.0\
          github:\
            repository: your-organization/your-repository # <--- add this field\
          ...        \
  ```\
</CodeBlock>\
\
<Callout intent="info">\
  SDK snippets automatically populated in your Fern Docs is a paid feature included\
  in the [SDK Starter plan](https://buildwithfern.com/pricing).\
</Callout>\
\
### Add the package name to your docs configuration\
\
Add the package name for the corresponding SDK to your `docs.yml` file. For Go, use the exact URL where the SDK repository is located.\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  navigation:\
    - api: API Reference\
      snippets:\
        python: your-package-name  # <--- needs to match the naming in generators.yml\
        typescript: your-package-name\
        go: https://github.com/your-organization/your-repository # <--- needs the https://github.com/ prefix\
  ```\
</CodeBlock>\
\
### Trigger generation\
\
As the final step, trigger your docs generation by running `fern generate --docs` locally or in CI/CD (i.e., GitHub Actions). The SDK snippets will now appear via a drop-down!\
\
### Set default snippet\
\
To set the default snippet shown in the API Reference drop-down, specify the `default-language` in your `docs.yml`.\
\
<CodeBlock title="docs.yml">\
  ```yaml \{1\}\
  default-language: typescript\
\
  navigation:\
    - api: API Reference\
      snippets:\
        python: your-package-name \
        typescript: your-package-name\
  ```\
</CodeBlock>\
\
## Language support\
\
TypeScript, Python, Go, and Ruby are the supported SDK code snippet languages. Our development work is driven by customer requests, so please request support for another language by [opening an issue](https://github.com/fern-api/fern/issues/new/choose).\
\
## Access via API\
\
If you'd like to bring SDK snippets into your own documentation, you can use the [Snippets API](/learn/cli-api/api-reference/snippets/get). API access requires a [SDK Business plan](https://buildwithfern.com/pricing) or above.\
\
Merge.dev is an example of a Fern customer that uses the Snippets API to bring Python code samples [into their API Reference](https://docs.merge.dev/hris/employees/#employees_list).\
\
## Endpoint request and response snippets\
\
Looking for information on generating API endpoint request and response snippets? See our documentation on [Endpoint Request Snippets](/learn/docs/content/components/request-snippet) and [Endpoint Response Snippets](/learn/docs/content/components/response-snippet).\
\
\
# API Playground\
\
> Reduce "time to 200" by allowing users to make real calls to your API from right within the API Reference.\
\
<Tip>\
  This feature is available on the Basic plan and above. \
\
  [Contact us](https://buildwithfern.com/contact)\
\
   to get set up.\
</Tip>\
\
Fern's API Playground allows users to make authenticated requests to your API without ever leaving your documentation.\
\
### Auto-populate with examples\
\
Fern will automatically populate the fields of the endpoint with the values set in your API specification.\
\
<div>\
  <iframe src="https://www.loom.com/embed/a48d921459b54dde9652c3fcc85ebc54?sid=2c0b4f4d-7e24-4fc5-a617-8d933195bfec?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen />\
</div>\
\
### Authenticated sessions\
\
Once a user sets their authentication credentials once, their credentials persist throughout their entire exploration.\
\
<div>\
  <iframe src="https://www.loom.com/embed/7de9948ae878448094b5e92da5effd41?sid=702889b7-aa3d-4669-994e-83c196d7bc3e?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen />\
</div>\
\
<Info>\
  Authentication credentials are only stored client-side using cookies. No sensitive user information is collected or stored.\
</Info>\
\
### Multiple environments\
\
Allow users to test their calls in a sandbox environment or select the environment relevant to them. Users can switch between multiple environments. Once they've selected their environment, it persists throughout their entire exploration.\
\
<div>\
  <iframe src="https://www.loom.com/embed/cb642161678e41cabcb677b900006f40?sid=5e45243c-3ba1-45cf-860b-72eee1970fc5?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen />\
</div>\
\
### WebSocket Playground\
\
For APIs that support WebSocket connections, the API Playground includes a **WebSocket**-specific Playground. The WebSocket Playground also allows users to establish a connection with the API, and send/receive messages in real-time.\
\
<div>\
  <iframe src="https://www.loom.com/embed/be4da30404794e9983c4fe639f78d4c8?sid=73b7aeda-98fa-4531-87ed-1e5909500fe2?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen />\
</div>\
\
\
# Auto-populate API keys\
\
> Make integrating with your API frictionless by adding your login flow to the API Playground.\
\
<Tip>\
  This feature is available on the Enterprise plan. [Contact us](https://buildwithfern.com/contact) to learn more.\
</Tip>\
\
Fern can integrate with your authentication flow, allowing users to login and have their API key automatically populated with the click of a button.\
\
<div>\
  <iframe src="https://www.loom.com/embed/790eb5849f1c4622aae09527908fdc7a?sid=d77062f8-35c3-41ab-8669-4c28b62e233b?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen />\
</div>\
\
With this feature, you can **create new users of your API** directly from within your documentation.\
\
\
# Advanced configuration\
\
> Configure advanced settings like the server URLs reachable by the API playground and authentication with OAuth.\
\
If you subscribe to Fern's Pro or Enterprise Plans, you can customize your API Playground settings to suit your customers needs.\
\
All configuration settings are defined in the `docs.yml` file, under API Reference navigation configuration, in a `Playground` object.\
\
### Filtering Server Urls\
\
If you have multiple environments for your API, you can filter the server URLs that are displayed in the API Playground.\
\
To filter server URLs, add the `environments` property to the `PlaygroundSettings` object in your `docs.yml`, like so:\
\
```yaml\
navigation:\
  api:\
    playground: \
      environments:\
        - Staging-A\
        - Staging-B\
```\
\
### Enabling OAuth 2.0 Authorization Injection\
\
If you have defined an endpoint that executes OAuth 2.0 Client Credentials Authorization in your API definition, you can enable OAuth 2.0 Authorization Injection in your API Playground.\
More information on enabling OAuth 2.0 Authorization Injection can be found [here](/learn/api-definition/fern/authentication#oauth-client-credentials).\
\
To enable OAuth 2.0 Authorization Injection, simply add the `oauth` feature flag to the `PlaygroundSettings` object in your `docs.yml`, like so:\
\
```yaml\
navigation:\
  api: \
    playground:\
      oauth: true\
```\
\
\
# Endpoint errors configuration\
\
> Enable errors to show up on the endpoint pages of your documentation, from the error names, codes, and objects returned configured in your API definition.\
\
This configuration enables errors to show up on the endpoint pages of your documentation. The error names, codes, and objects returned are configured in your API definition.\
\
## Configuration\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  navigation:\
    - api: API Reference\
      display-errors: true #<--- add this line\
  ```\
</CodeBlock>\
\
## Example\
\
<Frame>\
  ![Endpoint errors](https://fern-image-hosting.s3.amazonaws.com/fern/errors.png)\
</Frame>\
\
By clicking on an error, you can see the error name, code, and object returned. The response also updates to show the error object.\
\
<Frame>\
  ![Endpoint errors when expanded](https://fern-image-hosting.s3.amazonaws.com/fern/errors-expanded.png)\
</Frame>\
\
\
# Audiences\
\
> Use audiences to filter the endpoints, schemas, and properties that are displayed in your API Reference.\
\
Audiences are a useful tool for segmenting your API for different consumers. Common examples of audiences include `public`\
and `beta`. You can configure audiences in both [the OpenAPI Specification](/learn/api-definition/openapi/audiences) as well as [the Fern Definition](/learn/api-definition/fern/audiences).\
\
Once you've added audiences to your API Specification, you can filter to that audience by adding the `audience` property to the `api` object in your `docs.yml` navigation.\
\
<CodeBlocks>\
  ```yaml title="docs.yml" \{3-4\}\
  navigation:\
    - api: API Reference\
      audiences:\
        - public\
  ```\
</CodeBlocks>\
\
Here's [an example from Schematic](https://github.com/SchematicHQ/schematic-fern-config/blob/e19f5ea69a343727ed018e79127bf4fd20ad0f7b/fern/docs.yml#L128-L129) in production.\
\
\
# Customize API Reference layout\
\
> Customize your API Reference's naming, ordering, and structure.\
\
When you [include an API in your `docs.yml` file](/learn/docs/api-references/generate-api-ref), you can customize how the endpoints and sections are displayed in the sidebar navigation. By default, the reference will generate a navigation hierarchy based on the structure of the API spec, but several customizations can be configured.\
\
<Note title="API Sections">\
  If you are using an OpenAPI Specification, sections are created based on the `tags` property, converted to `lowerCamelCase` convention (e.g., createUser). If you are using a Fern Definition, sections are created based on the [`service`](/learn/api-definition/fern/endpoints#service-definition) file names.\
</Note>\
\
If you would like to only display a subset of endpoints, read more about the Audiences property for [OpenAPI Specifications](/learn/api-definition/openapi/audiences) or [Fern Definitions](/learn/api-definition/fern/audiences).\
\
## Ordering the API Reference\
\
### Alphabetizing endpoints and sections\
\
To sort all sections and endpoints alphabetically, unless explicitly ordered in `layout`, set `alphabetized` to `true`.\
\
```yaml title="docs.yml"\
navigation: \
  - api: API Reference\
    alphabetized: true\
```\
\
### Ordering top-level sections\
\
The `layout` option allows you to specify the order of sub-packages, sections, endpoints, and pages at the top level of your API Reference.\
\
<Tabs>\
  <Tab title="OpenAPI Specification">\
    ```yaml title="docs.yml"\
    navigation: \
      - api: API Reference\
        layout: \
          - POST /user\
          - user\
          - store\
          - plant\
    ```\
  </Tab>\
\
  <Tab title="Fern Definition">\
    ```yaml title="docs.yml"\
    navigation: \
      - api: API Reference\
        layout: \
          - user.create\
          - user\
          - store\
          - plant\
    ```\
  </Tab>\
</Tabs>\
\
<Frame>\
  <img src="file:20e8bc96-6636-424c-a15a-28c84230714c" alt="Ordered API Reference" />\
</Frame>\
\
### Ordering section contents\
\
Adding a `:` after the section name allows you to specify the order of its nested sub-packages and endpoints.\
\
<Note title="Referencing Endpoints">\
  To reference an endpoint, you can use either:\
\
  * `METHOD /path/name` (best for OpenAPI Specification)\
  * `serviceName.endpointName` (best for Fern Definition)\
</Note>\
\
<Tabs>\
  <Tab title="OpenAPI Specification">\
    You can reference an endpoint using the format `METHOD /path`.\
\
    ```yaml title="docs.yml"\
    navigation: \
      - api: API Reference\
        layout: \
          - user: \
              - POST /user\
              - PUT /user/\{username\}\
              - DELETE /user/\{username\}\
    ```\
  </Tab>\
\
  <Tab title="Fern Definition">\
    You can reference an endpoint using the format `serviceName.endpointName`.\
\
    ```yaml title="docs.yml"\
    navigation: \
      - api: API Reference\
        layout: \
          - user: \
              - user.create\
              - user.update\
              - user.delete        \
    ```\
  </Tab>\
</Tabs>\
\
<Frame>\
  <img src="file:44b1bd48-cf3f-4500-80f7-4d876b6fb437" alt="Content ordered in the API Reference" />\
</Frame>\
\
## Customizing the API Reference\
\
### Flattening sections\
\
To remove the API Reference title and display the section contents, set `flattened` to `true`.\
\
```yaml title="docs.yml"\
navigation: \
  - api: API Reference\
    flattened: true\
```\
\
<Frame>\
  <img src="file:c2a026e4-77b4-4187-8cc0-bed26723ec38" alt="Flattened API Reference" />\
</Frame>\
\
### Styling endpoints\
\
To customize the display of an endpoint, you can expand the endpoint description to include a `title` and `slug`, or set the endpoint as `hidden`.\
\
<Tabs>\
  <Tab title="OpenAPI Specification">\
    ```yaml title="docs.yml"\
    navigation: \
      - api: API Reference\
        layout: \
          - user: \
              - endpoint: POST /user\
                title: Create a User\
                slug: user-creation\
              - DELETE /user/\{username\}\
    ```\
  </Tab>\
\
  <Tab title="Fern Definition">\
    ```yaml title="docs.yml"\
    navigation: \
      - api: API Reference\
        layout: \
          - user: \
              - endpoint: user.create\
                title: Create a User\
                slug: user-creation\
              - user.delete\
    ```\
  </Tab>\
</Tabs>\
\
<Frame>\
  <img src="file:83a49b11-6d3a-4e1f-88b4-4feac15aa448" alt="Setting an endpoint title" />\
</Frame>\
\
### Adding custom sections\
\
You can add arbitrary folders in the sidebar by adding a `section` to your API Reference layout. A section can comprise entire groups of endpoints, individual endpoints, or even just Markdown pages. Sections can be customized by adding properties like a `icon`, `summary`, `slug` (or `skip-slug`), and `contents`.\
\
<Tabs>\
  <Tab title="OpenAPI Specification">\
    ```yaml title="docs.yml"\
    navigation: \
      - api: API Reference\
        layout: \
          - section: My Section\
            icon: flower\
            contents: \
              - PUT /user/\{username\}\
              - plant\
    ```\
  </Tab>\
\
  <Tab title="Fern Definition">\
    ```yaml title="docs.yml"\
    navigation: \
      - api: API Reference\
        layout: \
          - section: My Section\
            icon: flower\
            contents: \
              - user.update\
              - plant\
    ```\
  </Tab>\
</Tabs>\
\
<Frame>\
  <img src="file:90999876-4425-4d49-a2b2-19cb4bea8b73" alt="Custom section in the API Reference" />\
</Frame>\
\
### Adding a section overview\
\
The `summary` property allows you to add an `.md` or `.mdx` page as an overview of the API Reference or a section.\
\
```yaml title="docs.yml"\
navigation: \
  - api: API Reference\
    summary: pages/api-overview.mdx\
    layout: \
      - user: \
          summary: pages/user-overview.mdx\
```\
\
<Frame>\
  <img src="file:aee9313d-2869-4864-8c75-34ddea10bdcd" alt="API Reference with a summary page" />\
</Frame>\
\
### Adding pages and links\
\
You can add regular pages and external links within your API Reference.\
\
```yaml title="docs.yml"\
navigation: \
  - api: API Reference\
    layout: \
      - user: \
          contents: \
            - page: User Guide\
              path: ./docs/pages/user-guide.mdx\
            - link: Link Title\
              href: http://google.com\
```\
\
### Disable long-scrolling\
\
By default, the API Reference renders all endpoints on a single page (long-scrolling). To create separate pages for each endpoint, set `paginated: true`.\
\
```yaml title="docs.yml"\
navigation: \
  - api: API Reference\
    paginated: true\
```\
\
\
# Write Markdown content in your API Reference\
\
> Add Markdown content to your API Reference including summary pages and content between endpoints.\
\
Fern Docs allows you to write Markdown content in your API Reference documentation. This feature is useful for providing additional context, examples, or explanations for your API endpoints. There are a few ways to accomplish this:\
\
## In OpenAPI\
\
If you're using OpenAPI to define your API, you can include Markdown content in your OpenAPI Specification.\
\
For example, you can include a [callout](/learn/docs/content/components/callouts#note-callouts) in the `description` field of an endpoint:\
\
```yaml title="api/openapi.yml"\
paths:\
  /pets:\
    get:\
      summary: List all pets\
      description: |\
        Get a list of all pets in the system.\
\
        <Note>This endpoint requires authentication.</Note>\
```\
\
## In Fern Definition\
\
If you're using Fern's simpler API definition format, you can include Markdown content in your API definition.\
\
For example, you can include a [callout](/learn/docs/content/components/callouts#note-callouts) in the `docs` field of an endpoint:\
\
```yaml title="api/service.yml"\
service:\
  endpoints:\
    get:\
      path: /pets\
      docs: |\
        Get a list of all pets in the system.\
\
        <Note>This endpoint requires authentication.</Note>\
```\
\
## Adding a summary page\
\
You can also create a Markdown page that provides an overview of your API Reference. This page can include general information about your API, such as authentication requirements, rate limits, or other important details.\
\
To add a summary page, create a Markdown file in your `fern/` folder and link to it in your `docs.yml` file:\
\
```yaml title="docs.yml"\
navigation:\
  - api: API Reference\
    summary: ./pages/api-summary.mdx\
```\
\
By including the `summary` field, the `API Reference` section title will link to the `api-summary.mdx` page.\
\
## Adding Markdown content between endpoints\
\
In addition to adding Markdown content to individual endpoints, you can also include Markdown content between endpoints in your API Reference. This content can provide context or explanations that apply to multiple endpoints.\
\
This feature requires you to use the `layout` field in your `docs.yml` file, which is described in the [Customize your API Reference](/learn/docs/api-references/customize-api-reference-layout) guide.\
\
To add Markdown content between endpoints, create a Markdown file in your `fern/` folder and link to it in your `docs.yml` file:\
\
```yaml title="docs.yml"\
navigation:\
  - api: API Reference\
    layout:\
      - pet:\
          - page: Pet CRUD\
            path: ./pages/pet-crud.mdx\
          - addPet\
          - updatePet\
          - deletePet\
          - page: Pet Search\
            path: ./pages/pet-search.mdx\
          - findPets\
          - findPetsByStatus\
          - findPetsByTags\
          - findPetsByType\
          - findPetsByBreed\
```\
\
\
# Integrations\
\
> Integrate with third party platforms for analytics, support, etc.\
\
<CardGroup cols=\{2\}>\
  <Card title="PostHog" href="/learn/docs/integrations/analytics/posthog" horizontal icon=\{<img src="https://cdn.brandfetch.io/id2veLU_gI/idG9S94wXO.svg" />\} iconSize=\{12\} />\
\
  <Card\
    title="Segment"\
    href="/learn/docs/integrations/analytics/segment"\
    horizontal\
    icon=\{\
    <img src="https://cdn.brandfetch.io/idiousYjQz/theme/dark/symbol.svg?k=id64Mup7ac&t=1717151164256?t=1717151164256" />\
  \}\
    iconSize=\{12\}\
  />\
\
  <Card title="FullStory" href="/learn/docs/integrations/analytics/fullstory" horizontal icon=\{<img src="https://cdn.brandfetch.io/idRtIBDum6/w/400/h/400/theme/dark/icon.jpeg" />\} iconSize=\{12\} />\
\
  <Card title="Intercom" href="/learn/docs/integrations/support/intercom" horizontal icon=\{<img src="https://cdn.brandfetch.io/idYJNDWF1m/theme/dark/symbol.svg" />\} iconSize=\{12\} />\
\
  <Card title="Postman" href="/learn/docs/integrations/postman" horizontal icon=\{<img src="https://seeklogo.com/images/P/postman-logo-0087CA0D15-seeklogo.com.png" />\} iconSize=\{12\} />\
</CardGroup>\
\
## Enabling Analytics\
\
You can define your analytics configuration in `docs.yml`. You only need to include entries for the platforms you want to connect.\
\
```yaml docs.yml\
analytics:\
  posthog:\
    api-key: $\{POSTOHG_API_KEY\}\
    endpoint: https://self.hosted.posthog.com/\
  segment:\
    write-key: $\{SEGMENT_WRITE_KEY\}\
  intercom:\
    app-id: $\{INTERCOM_APP_ID\}\
    endpoint: https://intercom.custom-instance.com/\
  fullstory:\
    org-id: $\{FULLSTORY_ORG_ID\}\
```\
\
### Environment Variables\
\
If your docs configuration is public, then we do not advise adding secret values directly to `docs.yml`.\
Instead, you can reference an environment variable by using the syntax `$\{VARIABLE_NAME\}`.\
\
<Note>\
  If you are using GitHub Workflows to trigger docs generation, you must make sure that the environment variables\
  are available during the workflow run.\
\
  ```yaml \{4\}\
  - name: Publish Docs\
    env:\
      FERN_TOKEN: $\{\{ secrets.FERN_TOKEN \}\}\
      POSTHOG_API_KEY: $\{\{ secrets.POSTHOG_PROJECT_API_KEY \}\}\
    run: |\
      npm install -g fern-api\
      fern generate --docs\
  ```\
</Note>\
\
## Postman\
\
<Info>\
  The Postman integration is not configured in `docs.yml`. Check out this [page](/learn/docs/integrations/postman) to\
  learn more.\
</Info>\
\
\
# Google Analytics\
\
> Add Google Analytics to your Docs with Fern.\
\
Fern supports integrating with both [Google Analytics 4](https://developers.google.com/analytics) and [Google Tag Manager](https://tagmanager.google.com/).\
\
<Tip>\
  This feature is available on the Fern Basic plan and above. Reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com) to set up your Google Analytics.\
</Tip>\
\
\
# PostHog\
\
> Learn how to integrate PostHog with Fern Docs!\
\
## Add Posthog to your Docs\
\
To integrate PostHog, you'll need a Posthog API Key, and optionally, you can configure a custom Posthog host.\
\
### Integrate Posthog\
\
You can find your PostHog API Key under your [project settings.](https://us.posthog.com/settings/project)\
\
Then, in your `docs.yml` file, add your Posthog configuration:\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  analytics:\
    posthog:\
      api-key: $\{POSTHOG_API_KEY\} # reads your api key from environment variables\
      # Optional\
      endpoint: $\{POSTHOG_API_HOST\} # e.g. https://analytics.example.com or https://eu.i.posthog.com\
  ```\
</CodeBlock>\
\
\
# Fullstory\
\
> Learn how to integrate Fern Docs with Fullstory to track user behavior and analytics.\
\
## Add Fullstory to your Docs\
\
To add Fullstory to your Docs, you need to add your Fullstory `orgId` to your `docs.yml` file.\
\
### Get your Fullstory Org ID\
\
When you login to your Fullstory account, your Org ID can be found in the URL of your browser.\
\
```\
https://app.fullstory.com/ui/<ORG_ID>/home\
```\
\
Additionally, you can find your Org ID in [Settings > Data Capture and Privacy > Fullstory Setup](https://help.fullstory.com/hc/en-us/articles/360047075853-How-do-I-find-my-Fullstory-Org-Id#:~:text=You%20can%20find%20your%20Org,embedded%20in%20the%20Fullstory%20snippet.\\&text=More%20information%20about%20installation%20and,the%20URL%20of%20your%20browser.)\
inside the Fullstory snippet:\
\
1. Log in to your Fullstory account.\
2. Find **Settings** in a dropdown by clicking your organization's name or logo in the top left.\
3. Navigate the sidebar to the Data Capture and Privacy section. Click on "Fullstory Setup", located under the heading.\
4. Retrieve the Org Id from the snippet, where it is assigned to `window['_fs_org']`. It will appear as `window['_fs_org'] = '<ORG_ID>'`.\
\
You can find visual instructions in [Fullstory's guide](https://help.fullstory.com/hc/en-us/articles/360047075853-How-do-I-find-my-Fullstory-Org-Id#:~:text=You%20can%20find%20your%20Org,embedded%20in%20the%20Fullstory%20snippet.\\&text=More%20information%20about%20installation%20and,the%20URL%20of%20your%20browser.)\
about this topic.\
\
### Integrate Fullstory with your Docs\
\
In your `docs.yml` file, add your Fullstory Org ID:\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  analytics:\
    fullstory:\
      org-id: $\{FULLSTORY_ORG_ID\} # reads your org id from environment variables\
  ```\
</CodeBlock>\
\
\
# Segment\
\
> Learn how to integrate Fern Docs with Segment to track user behavior and analytics.\
\
<Note>\
  Currently we only support Segment via a custom writeKey in the docs.yml file, however you can add other providers to your docs page through [Custom Javascript](/learn/docs/building-your-docs/custom-css-global-js).\
  We are also working on adding support for additional analytics tools via the docs.yml file analytics block!\
</Note>\
\
## Add Segment to your Docs\
\
To add Segment to your Docs, you need to add the Segment writeKey to your `docs.yml` file.\
\
### Get your Segment writeKey\
\
1. Log in to your Segment account.\
2. Go to the workspace where you want to add the Docs integration.\
3. Click on the Source you want to track.'\
4. Click on the `Settings` tab.\
5. Copy the `Write Key` from the `API Keys` section.\
\
### Add the Segment writeKey to your Docs\
\
In your `docs.yml` file, add the Segment writeKey:\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  analytics:\
    segment:\
      write-key: $\{SEGMENT_WRITE_KEY\} # scans environment variable\
  ```\
</CodeBlock>\
\
\
# Intercom\
\
> Learn how to integrate Intercom with Fern Docs!\
\
## Add Intercom to your Docs\
\
To add Intercom to your Docs, you need to your Intercom `app_id`, also known as the Intercom workspace ID.\
This is a unique code assigned to your app when you create it in Intercom.\
\
Additionally, you may configure a custom Intercom endpoint.\
\
### Get your Intercom App Id\
\
Your app ID is available under [Settings > Workspace > General](https://app.intercom.com/a/apps/_/settings/workspace/general)\
in the "Workspace name & time zone" tab.\
\
See [Intercom's FAQ](https://www.intercom.com/help/en/articles/8771110-getting-started-faqs#h_c12f89cf9d) for visual instructions.\
\
### Integrate Intercom with your Docs\
\
In your `docs.yml` file, add your Intercom config:\
\
<CodeBlock title="docs.yml">\
  ```yaml\
  analytics:\
    intercom:\
      app-id: $\{INTERCOM_APP_ID\} # reads your org id from environment variables\
      # Optional\
      endpoint: $\{INTERCOM_ENDPOINT\} # e.g. https://intercom.custom-instance.com\
  ```\
</CodeBlock>\
\
\
# Postman Integeration\
\
> Generate a postman collection full of example requests and responses\
\
## Showcase\
\
<CardGroup cols=\{2\}>\
  <Card title="Primer" href="https://www.postman.com/primerio/workspace/primer-docs/overview" horizontal icon=\{<img src="https://cdn.prod.website-files.com/5e9dc792e1210c5325f7ebbc/64b039144f484892355032dd_62146168.png" />\} iconSize=\{12\} />\
\
  <Card title="MirrorWOrld" href="https://developer.mirrorworld.fun/" horizontal icon=\{<img src="https://cdn.brandfetch.io/idLEJUb6Vb/w/400/h/400/theme/dark/icon.jpeg" />\} iconSize=\{12\} />\
</CardGroup>\
\
## Getting started\
\
The configuration for the postman generator lives in your fern folder, in a file\
called [`generators.yml`](/learn/api-definition/introduction/what-is-the-fern-folder#generatorsyml).\
\
### **Step 1**: Configure your `generators.yml`\
\
Start by running the following command:\
\
```sh\
fern add fern-postman --group postman\
```\
\
Once the command completes, you will see the following configuration added:\
\
```yaml title="generators.yml" \{2-8\}\
groups:\
  postman:\
    generators:\
      - name: fernapi/fern-postman\
        version: 0.0.45\
        output:\
          location: local-file-system\
          path: ../postman\
```\
\
### **Step 2**: Generate a `collection.json`\
\
Start by running the following command\
\
```sh\
fern generate --group postman\
```\
\
This will trigger postman collection on Fern's cloud. Once complete, you'll see a `collection.json`:\
\
```bash \{4-5\}\
fern/\
  \uc0\u9500 \u9472  fern.config.json\
  \uc0\u9500 \u9472  generators.yml\
postman\
  \uc0\u9500 \u9472  collection.json\
```\
\
## Publishing\
\
If you'd like Fern to publish the collection directly to Postman instead, you can modify your `generators.yml` configuration\
in the following way:\
\
```yaml title="generators.yml" \{6-9\}\
generators:\
  postman:\
    generators:\
      - name: fernapi/fern-postman\
        version: 0.4.0\
        output:\
          location: postman\
          api-key: $\{POSTMAN_API_KEY\}\
          workspace-id: 07e228e5-3f91-4223-8e27-bbfe4a81a601\
        config:\
          collection-name: My collection name\
```\
\
If you'd like to publish to a particular collection, just specify the collection ID.\
\
```yaml title="generators.yml" \{10\}\
generators:\
  postman:\
    generators:\
      - name: fernapi/fern-postman\
        version: 0.4.0\
        output:\
          location: postman\
          api-key: $\{POSTMAN_API_KEY\}\
          workspace-id: 07e228e5-3f91-4223-8e27-bbfe4a81a601\
          collection-id: 21510182-14b07230-46e2-431e-8153-d5c7d217b214\
        config:\
          collection-name: My collection name\
```\
\
\
# Hosting with GitLab\
\
To host your Fern docs using GitLab, you will need to [add a Fern token to your repository variables](/learn/docs/developer-tools/gitlab#add-a-token-to-gitlab).\
\
## Add a token to GitLab\
\
<Steps>\
  ### Log in\
\
  Log into [GitLab](https://gitlab.com/users/sign_in).\
\
  ### Navigate to CI/CD in settings\
\
  Click on the **Settings** tab in your repository. Then, click on **CI/CD**.\
\
  ### Add variable\
\
  Scroll to the **Variables** section and select **Expand** > **Add variable**. Add your key and value, *deselect* **Protect variable**, and then click **Save changes**.\
</Steps>\
\
## Preview docs with GitLab\
\
<Steps>\
  ### Contact us\
\
  To get set up with a GitLab pipeline to preview your docs automatically, reach out via your dedicated Slack channel or [email](mailto:support@buildwithfern.com).\
\
  ### Log in\
\
  Log into [GitLab](https://gitlab.com/users/sign_in).\
\
  ### Navigate to Access Tokens\
\
  Click on the **Settings** tab in your repository. Then, click on **Access Tokens**.\
\
  ### Generate project access token\
\
  Click on **Add new token**. You then need to:\
\
  * Add your token name\
  * Select an expiry date (note: once the token expires, you will need to generate a new one)\
  * Set role to **Reporter**\
  * Set scope to **api**\
\
  When finished, click **Create project access token**.\
\
  <Note title="Save your token">\
    Be sure to save the generated token - it won't be displayed after you leave the page.\
  </Note>\
\
  ### Add token to repository variables\
\
  You can do this using [the steps listed above](/learn/docs/developer-tools/gitlab#add-a-token-to-gitlab).\
</Steps>\
\
\
# Using Vale\
\
## What is Vale?\
\
[Vale](https://vale.sh/) is an open-source tool for linting content from a variety of different file types, including Markdown.\
\
## Using Vale with MDX\
\
Once installed, you can use Vale with MDX files by adding a `.vale.ini` file to your Fern repo.\
\
<Tip>\
  Be sure to add\
\
  ```txt\
  [formats]\
  mdx = md\
  ```\
\
  to your `.vale.ini` configuration so the MDX format is recognized.\
</Tip>\
\
To use Vale's HTML-style comments (`<!-- comment -->`) in an MDX file, wrap within an MDX-styled comment (`\{/* comment */\}`). For example:\
\
* **disable Vale**: `\{/* <!-- vale off --> */\}`\
* **enable Vale**: `\{/* <!-- vale on --> */\}`\
\
```markdown title='Example Vale Usage'\
Vale will check this text.\
\
\{/* <!-- vale off --> */\}\
\
Vale won't check this text.\
\
\{/* <!-- vale on --> */\}\
\
Vale will start checking this text again.\
```\
\
\
# Overview\
\
> Overview of the Fern CLI including usage, installation, and CI/CD environments\
\
Use the Fern CLI to manage and test your documentation, SDKs, permissions, and API specification from the terminal or via an automated system.\
\
Check out the [API Reference](/learn/cli-api/api-reference/) to interact with Fern programmatically.\
\
## Installing Fern CLI\
\
Run the following command to download and install Fern CLI from the [npm](https://www.npmjs.com/) registry.\
\
```bash\
npm install -g fern-api\
```\
\
## Updating Fern CLI\
\
When there is a newer version of Fern CLI available, running any command will trigger an alert. To update Fern, run the same installation command yet again.\
\
```bash\
npm install -g fern-api@latest\
```\
\
<Note>\
  Run `fern upgrade` to update the Fern CLI *and* your project's generators.\
</Note>\
\
## Checking the version\
\
Use `--version`, shorthand `-v`, to check the Fern CLI version currently being used.\
\
```bash\
fern -v\
0.26.10\
```\
\
## Authentication and CI/CD\
\
Fern CLI requires authentication before accessing an organization\'92s resources. To authenticate manually, login using GitHub using `fern login`. To enable Fern CLI use in CI/CD environments, and for an example showing how to set up Fern and GitHub Actions, check out [`fern token`](/learn/cli-api/cli-reference/commands#fern-token).\
\
\
# Global options\
\
> Global options for the Fern CLI\
\
Global options are available to use with many Fern CLI commands. Read more below.\
\
## help\
\
Use the `--help` option with any Fern CLI command to see an explanation and available options.\
\
<CodeBlocks>\
  ```bash maxLines=10 title="fern add --help"\
  fern add --help\
  fern add <generator>\
\
  Add a code generator to generators.yml\
\
  Positionals:\
    generator                                                [string] [required]\
\
  Options:\
    --help     Show help                                               [boolean]\
    --log-level    [choices: "debug", "info", "warn", "error"] [default: "info"]\
    --api      Only run the command on the provided API                 [string]\
    --group    Add the generator to the specified group                 [string]\
  ```\
\
  ```bash maxLines=10 title="fern write-definition --help"\
  fern write-definition --help\
  fern write-definition\
\
  Write underlying Fern Definition for OpenAPI Specifications and API Dependencies.\
\
  Options:\
    --help     Show help                                               [boolean]\
    --log-level    [choices: "debug", "info", "warn", "error"] [default: "info"]\
    --api      Only run the command on the provided API                 [string]\
  ```\
</CodeBlocks>\
\
## log-level\
\
Use the `--log-level` option to see more information about Fern's actions.\
\
* debug: Debug messages, informational messages, warnings, and errors are logged.\
* **info \\[default]**: Informational messages, warnings, and errors are logged.\
* warn: Warnings and errors are logged.\
* error: Only error messages are logged.\
\
```bash\
fern generate --log-level debug\
```\
\
\
# Commands\
\
> Fern CLI command documentation\
\
Explore documentation for popular Fern CLI commands.\
\
<AccordionGroup toc=\{true\}>\
  <Accordion title="fern check">\
    Use `fern check` to validate your API definition and Fern configuration: `fern.config.json`, `generators.yml`, and `docs.yml`.\
\
    When successfully executed, this command will not produce any output.\
\
    <CodeBlock title="terminal">\
      ```bash\
      fern check [--api <api>] [--warnings]\
      ```\
    </CodeBlock>\
\
    ### api\
\
    Use `--api <api>` to specify which API you'd like to check.\
\
    ```bash\
    fern check --api public-api\
    ```\
\
    ### warnings\
\
    Use `--warnings` to log warnings in addition to errors.\
\
    ```bash\
    fern check --warnings\
    ```\
\
    ## Usage in a GitHub Action\
\
    <CodeBlock title=".github/workflows/fern-check.yml">\
      ```yml maxLines=14 \
      name: Fern Validation Check\
\
      on:\
      pull_request:\
      branches: - main\
\
      jobs:\
      validate-fern-api:\
      name: Validate using Fern's linter\
      runs-on: ubuntu-latest\
\
          steps:\
          - name: Checkout repository\
              uses: actions/checkout@v4\
\
          - name: Set up Node.js\
              uses: actions/setup-node@v2\
              with:\
              node-version: '14'\
\
          - name: Install Fern\
              run: npm install -g fern-api\
\
          - name: Validate API with Fern\
              run: fern check\
\
      ```\
    </CodeBlock>\
  </Accordion>\
\
  <Accordion title="fern generate">\
    Use `fern generate` to run the Fern compiler and create SDKs for your API.\
\
    <CodeBlock title="terminal">\
      ```bash\
      fern generate [--group <group>] [--api <api>] [--version <version>] [--local] [--keepDocker]\
      ```\
    </CodeBlock>\
\
    ### group\
\
    Use `--group <group>` to filter to a specific group within `generators.yml`. Required unless you have a `default-group` declared in `generators.yml`.\
\
    ```bash\
    fern generate --group internal\
    ```\
\
    ### api\
\
    Use `--api <api>` to specify the API for SDK generation.\
\
    ```bash\
    fern generate --api public-api\
    ```\
\
    ### version\
\
    Use `--version` to specify a version for SDKs and documentation. Adherance to [semantic versioning](https://semver.org/) is advised.\
\
    ```bash\
    fern generate --version 2.11\
    ```\
\
    ### local\
\
    Use `--local` to generate code locally by downloading the Docker Image and running it on your machine.\
    Note that running Docker locally supports outputting files, and not publishing to package managers.\
\
    ```bash\
    fern generate --local\
    ```\
\
    <Warning>\
       \
\
      [Docker Desktop](https://www.docker.com/products/docker-desktop/)\
\
       must be installed and running on your machine. \
    </Warning>\
\
    ### keepDocker\
\
    Use `--keepDocker` to keep the Docker container running after the generation is complete. This is useful for debugging.\
\
    ```bash\
    fern generate --local --keepDocker\
    ```\
\
    <Warning>\
       \
\
      [Docker Desktop](https://www.docker.com/products/docker-desktop/)\
\
       must be installed and running on your machine. \
    </Warning>\
  </Accordion>\
\
  <Accordion title="fern generate --docs">\
    Use `fern generate --docs` to create a documentation site for your API.\
\
    <CodeBlock title="terminal">\
      ```bash\
      fern generate --docs [instance <instance-url>] [--preview]\
      ```\
    </CodeBlock>\
\
    ### instance\
\
    Use `--instance` to specify which instance URL in your `docs.yml` to generate documentation for.\
\
    ```bash\
    fern generate --docs --instance your-organization.docs.buildwithfern.com\
    ```\
\
    ### preview\
\
    Use `--preview` to preview updates to your documentation before publishing changes to your production site.\
\
    ```bash\
    fern generate --docs --preview\
    ```\
  </Accordion>\
\
  <Accordion title="fern docs dev">\
    Use `fern docs dev` to run a local development server to preview your docs.\
\
    <CodeBlock title="terminal">\
      ```bash\
      fern docs dev [--port <port-number>]\
      ```\
    </CodeBlock>\
\
    ### port\
\
    Use `--port <port-number>` to specify the port the docs preview will be run on.\
\
    ```bash\
    fern docs dev --port 57908\
    ```\
  </Accordion>\
\
  <Accordion title="fern upgrade">\
    Use `fern upgrade` will upgrade your compiler version in `fern.config.json` to the\
    latest version. It will also upgrade generators in `generators.yml` to their minimum-compatible versions.\
\
    <CodeBlock title="terminal">\
      ```bash\
      fern upgrade [--rc]\
      ```\
    </CodeBlock>\
\
    ### rc\
\
    Use `--rc` to upgrade to the compiler's latest release candidate. Using a release candidate is not recommended for production use.\
\
    ```bash\
    fern upgrade --rc\
    ```\
  </Accordion>\
\
  <Accordion title="fern init">\
    Use `fern init` to initialize a new Fern workspace in the current folder. By default, you\'92ll see the IMDb API example.\
\
    <CodeBlock title="terminal">\
      ```bash\
      fern init [--docs]\
      ```\
    </CodeBlock>\
\
    This will create the following folder structure in your project:\
\
    ```bash\
    fern/\
    \uc0\u9500 \u9472  fern.config.json # root-level configuration\
    \uc0\u9500 \u9472  generators.yml # generators you're using\
    \uc0\u9492 \u9472  definition/\
        \uc0\u9500 \u9472  api.yml  # API-level configuration\
        \uc0\u9492 \u9472  imdb.yml # endpoints, types, and errors\
    ```\
\
    ### docs\
\
    By adding `--docs`, you\'92ll also get a sample documentation website for your API with an API Reference section.\
\
    ```bash\
    fern init --docs\
    ```\
\
    The file added will contain:\
\
    ```yaml docs.yaml\
    instances:\
      - url: https://your-organization.docs.buildwithfern.com\
    title: Your Organization | Documentation\
    navigation:\
      - api: API Reference\
    colors:\
    accentPrimary: '#ffffff'\
    background: '#000000'\
    ```\
\
    To publish the API docs, run [`fern generate --docs`](/learn/cli-api/cli-reference/commands#fern-generate---docs).\
\
    <Tip>\
      For more information on getting started, check out our [Quickstart Guide](/learn/docs/getting-started/quickstart)\
    </Tip>\
  </Accordion>\
\
  <Accordion title="fern login">\
    Use `fern login` to login to the Fern CLI via GitHub. Logging in allows you\
    join GitHub organizations, gain permissions, and contribute to projects.\
\
    <CodeBlock title="terminal">\
      ```bash\
      fern login [--device code]\
      ```\
    </CodeBlock>\
\
    ### device-code\
\
    Use `--device-code` to login via device code authorization.\
\
    ```bash\
    fern login --device-code\
    ```\
\
    <Note>\
      To enable CI/CD, use [`fern token`](/cli-api/cli-reference/commands#fern-token).\
    </Note>\
  </Accordion>\
\
  <Accordion title="fern token">\
    Use `fern token `to generate a `FERN_TOKEN` specific to your organization defined\
    in `fern.config.json`. Use the token to authenticate with the API in CI. Tokens do not expire.\
\
    <CodeBlock title="terminal">\
      ```bash\
      fern token\
      ```\
    </CodeBlock>\
\
    ## GitHub Actions\
\
    If using GitHub Actions as your CI, add the `FERN_TOKEN` as a [GitHub Action secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) in your Fern configuration repo.\
    You can then reference the secret in your CI:\
\
    ```yaml\
    - name: Generate and Publish Documentation with Fern\
      env:\
          FERN_TOKEN: $\{\{ secrets.FERN_TOKEN \}\}\
      run: fern generate --docs\
    ```\
\
    See [the full example on GitHub](https://github.com/fern-api/fern/blob/main/.github/workflows/publish-docs.yml).\
  </Accordion>\
\
  <Accordion title="fern write-definition">\
    Use `fern write-definition` to convert your OpenAPI Specification into a Fern Definition.\
    You must have a `fern/openapi/` folder that contains an OpenAPI Specification file in `.json` or `.yaml` format.\
\
    <CodeBlock title="terminal">\
      ```bash\
      fern write-definition [--api <api>]\
      ```\
    </CodeBlock>\
\
    When run, this command creates a new folder within `fern/` called `.definition/`.\
\
    ```bash \{6-8\}\
    fern/\
    \uc0\u9500 \u9472  fern.config.json\
    \uc0\u9500 \u9472  generators.yml\
    \uc0\u9492 \u9472  openapi/\
        \uc0\u9492 \u9472  openapi.json\
      \uc0\u9492 \u9472  .definition/ # <--- your Fern Definition\
        \uc0\u9492 \u9472  api.yml\
        \uc0\u9492 \u9472  __package__.yml\
    ```\
\
    <Warning>\
      If you do not see the `.definition/` folder, use the appropriate command or configuration to view hidden folders (`ls -a` in `bash` and `zsh`).\
    </Warning>\
\
    If your `fern/` folder contains both an `openapi/` and a `definition/` folder, Fern defaults to reading your OpenAPI Specification. To use your Fern Definition as input, you must:\
\
    * Rename the `.definition/` folder to `definition/`.\
    * Remove or rename the `openapi/` folder. For example, you can rename it to `.openapi/`.\
\
    ### api\
\
    Use `--api` to specify the API to write the definition for if you have multiple defined in your `fern/apis/` folder.\
\
    ```bash\
    fern write-definition --api public-api\
    ```\
  </Accordion>\
\
  <Accordion title="fern write-overrides">\
    Use `fern write-overrides` to generate a basic OpenAPI overrides file. An overrides file allows for\
    reversible revisions to the API specification, including adding request and response examples for\
    code snippets in Fern Docs.\
\
    <CodeBlock title="terminal">\
      ```bash\
      fern write-overrides [--api <api>] [--exclude-models]\
      ```\
    </CodeBlock>\
\
    When run, this command creates a new file within `fern/openapi/` called `openapi-overrides.yml`.\
\
    ```bash \{5\}\
    fern/\
    \uc0\u9500 \u9472  fern.config.json\
    \uc0\u9500 \u9472  generators.yml\
    \uc0\u9492 \u9472  openapi/\
        \uc0\u9492 \u9472  openapi-overrides.yaml # <--- your overrides file\
        \uc0\u9492 \u9472  openapi.json\
    ```\
\
    ### api\
\
    Use `--api` to specify the API to run the command on if multiple are defined.\
\
    ```bash\
    fern write-overrides --api public-api\
    ```\
\
    ### exclude-models\
\
    Use `--exclude-models` to stub the models while generating the initial overrides (in addition to the endpoints).\
\
    ```bash\
    fern write-overrides --exclude-models\
    ```\
  </Accordion>\
</AccordionGroup>\
\
\
# December 11, 2024\
\
## 0.45.4\
\
**`(fix):`** Defaults are no longer set on datetimes when converting to docs shapes.\
\
\
# December 10, 2024\
\
## 0.45.4-rc1\
\
**`(chore):`** Bumped Java IR to latest (v53)\
\
\
# December 9, 2024\
\
## 0.45.4-rc0\
\
**`(fix):`** The CLI prompts the user to confirm output directory overwrites on fern generate.\
\
\
# December 5, 2024\
\
## 0.45.3\
\
**`(fix):`** Unknown schemas are no longer incorrectly marked as `additionalProperties: true`.\
\
\
# December 3, 2024\
\
## 0.45.2\
\
**`(fix):`** Example generation now respects read-only schemas when generating request examples.\
\
\
# November 29, 2024\
\
## 0.45.1-rc0\
\
**`(fix):`** Generate valid examples using spec validation information; respect `null` entries during example generation.\
\
\
# November 27, 2024\
\
## 0.45.1\
\
**`(internal):`** Add `inline` field to type declarations in the Fern definition and IR.\
Add support for importing inline types from OpenAPI into Fern definition and IR.\
\
\
# November 23, 2024\
\
## 0.45.0\
\
**`(internal):`** Several improvements to docs, conjure importer, and the cli.\
\
\
# November 22, 2024\
\
## 0.45.0-rc54\
\
**`(internal):`** Removes errant minimum and maximums for 'float' types for docs.\
\
\
# November 21, 2024\
\
## 0.45.0-rc50\
\
**`(fix):`** Increase max recursive depth allowed for example validation.\
\
\
# November 20, 2024\
\
## 0.45.0-rc49\
\
**`(fix):`** Add 'list' to reserved keywords for use in PHP generator.\
\
\
# November 19, 2024\
\
## 0.45.0-rc47\
\
**`(fix):`** Support SDK generation provided comma-delineated content-type values in OpenAPI specs.\
\
\
# November 18, 2024\
\
## 0.45.0-rc46\
\
**`(fix):`** The IR handles converting example unions that are aliases.\
\
\
# November 14, 2024\
\
## 0.45.0-rc44\
\
**`(fix):`** Update the IR's `ServiceTypeReferenceInfo` to include all transitive types\
referenced by a service.\
\
\
# November 13, 2024\
\
## 0.45.0-rc43\
\
**`(fix):`** Support non-standard HTTP code 498; Validate `x-fern-examples` during schema parsing.\
\
\
# November 12, 2024\
\
## 0.45.0-rc40\
\
**`(fix):`** Fixed bug in the Conjure importer where query parameters were overwritten during endpoint parameter parsing.\
\
\
# November 11, 2024\
\
## 0.45.0-rc39\
\
**`(fix):`** The OpenAPI importer now supports correlating request and response examples by name. When an example name is shared\
between a request body and response, they will be paired together in the generated Fern definition.\
\
\
# November 8, 2024\
\
## 0.45.0-rc36\
\
**`(fix):`** The OpenAPI importer now supports importing deep object query parameters. To do this, you will\
need to configure a setting in your `generators.yml`\
\
```yml\
api:\
 specs:\
   - openapi: ./path/to/openapi.yml\
     settings:\
       object-query-paramaters: true\
```\
\
\
# November 7, 2024\
\
## 0.45.0-rc34\
\
**`(internal):`** The CLI now recognizes the versions of the Go generator that require IRv53.\
\
\
# November 6, 2024\
\
## 0.45.0-rc33\
\
**`(feat):`** The Fern CLI now supports roles and viewers in your docs configuration, if you are on the enteprise plan for docs:\
\
```yml docs.ym\
roles:\
  - internal\
  - beta-users\
  - enterprise-users\
\
navigation:\
  - section: Internal Section\
    viewers:\
      - internal\
    contents:\
      - page: Internal Page\
        path: ./internal/page.mdx\
```\
\
\
# November 5, 2024\
\
## 0.45.0-rc32\
\
**`(fix):`** The OpenAPI importer now supports reading endpoints that have application/x-www-form-urlencoded requests\
\
\
# November 1, 2024\
\
## 0.45.0-rc29\
\
**`(feat):`** The OpenAPI importer now parses the `examples` field that may be present on OpenAPI 3.1 schemas.\
\
\
# October 29, 2024\
\
## 0.45.0-rc26\
\
**`(feat):`** `fern check` handles validating unions that contain base properties.\
\
\
# October 26, 2024\
\
## 0.45.0-rc25\
\
**`(internal):`** The Fern CLI temporarily does not support RBAC/Audiences (they will be added in again shortly).\
\
\
# October 25, 2024\
\
## 0.45.0-rc21\
\
**`(feat):`** The Fern CLI now supports orphaned pages in your docs configuration.\
\
**`(fix):`** The RBAC config model is now renamed to `roles` and `viewers`:\
\
```yml docs.yml\
roles:\
  - internal\
\
navigation:\
  - section: Internal Section\
    viewers:\
      - internal\
    contents:\
      - page: Internal Page\
        path: ./internal/page.mdx\
```\
\
\
# October 24, 2024\
\
## 0.45.0-rc18\
\
**`(fix):`** - Add additional debug logging to the CLI when downloading docs preview bundle\
\
\
# October 23, 2024\
\
## 0.45.0-rc16\
\
**`(fix):`** The Conjure importer now correctly keys the union subvariant by the property of the discriminant.\
\
```conjure\
union:\
  discriminant: type\
  union:\
    square: Square\
    circle: Circle\
```\
\
is equal to the following Fern Definition:\
\
```yml fern\
union:\
  discriminant: type\
  types:\
    square:\
      type: Square\
      key: square\
    circle:\
      type: Circle\
      key: circle\
```\
\
\
# October 22, 2024\
\
## 0.45.0-rc15\
\
**`(fix):`** The Conjure importer now correctly imports base-path and docs from your conjure definition.\
\
\
# October 21, 2024\
\
## 0.45.0-rc9\
\
**`(fix):`** Improved JSON Schema generation for object extensions and const values:\
\
* Object extensions are now properly represented using `allOf` in the JSON Schema\
* Literal values (string and boolean) are now correctly represented using `const` in the JSON Schema\
\
\
# October 20, 2024\
\
## 0.45.0-rc6\
\
**`(fix):`** Update the CLI package.json to include the correct files.\
\
\
# October 19, 2024\
\
## 0.45.0-rc5\
\
**`(feat):`** Introduce a new command `fern jsonschema <output-file> --type <type-name>`\
that outputs the JSON Schema for a given type in your Fern Definition.\
\
```sh\
fern jsonschema ./schema.json --type MyType\
```\
\
\
# October 16, 2024\
\
## 0.45.0-rc4\
\
**`(chore):`** SCIM has been added as a common initialism.\
\
\
# October 11, 2024\
\
## 0.45.0-rc3\
\
**`(fix):`** Numerous fixes to the Conjure API Importer such as reading in request bodies and query parameters.\
\
\
# October 10, 2024\
\
## 0.45.0-rc0\
\
**`(fix):`** The Docs now support rendering `additionalProperties` in the API Playground so that users can send out arbitrary key,value pairs.\
\
\
# October 9, 2024\
\
## 0.44.11\
\
**`(fix):`** Several improvements to the conjure importer.\
\
\
# October 7, 2024\
\
## 0.44.7\
\
**`(internal):`** The Fern CLI command `fern generator list` now accepts filters for the output mode, for example, you may now specify `fern generator list --excluded-modes local-file-system`\
in order to filter any generators from the list that are outputting locally.\
\
\
# October 6, 2024\
\
## 0.44.2\
\
**`(fix):`** Fern's OpenAPI importer can now handle multiple error schemas for the\
same status code.\
\
\
# October 5, 2024\
\
## 0.44.1\
\
**`(feat):`** The OpenAPI importer used to try and coerce all enums into a literals.\
In some cases this is not desirable, so we now expose an option called\
`coerce-enums-to-literals` in your generators.yml.\
\
```yml generators.yml\
api:\
  specs:\
    - openapi: ../openapi.json\
      overrides: ../openapi-overrides.yml\
      settings:\
        title-as-schema-name: false\
        coerce-enums-to-literals: false\
```\
\
\
# October 2, 2024\
\
## 0.44.0-rc0\
\
**`(feat):`** The Fern CLI now supports parsing [Conjure](https://github.com/palantir/conjure), Palantir's\
home-grown API Definition format.\
\
If you know a company that is using Conjure that wants API Docs + SDKs, send them our way!\
\
\
# September 30, 2024\
\
## 0.43.8\
\
**`(fix):`** Any markdown files that have custom components are also pushed up to the Fern Docs\
platform.\
\
\
# September 28, 2024\
\
## 0.43.7\
\
**`(fix):`** The `valid-markdown` rule has been updated to try and parse the markdown file into a\
valid AST. If the file fails to parse, `fern check` will log an error as well\
as the path to the markdown.\
\
\
# September 27, 2024\
\
## 0.43.6\
\
**`(fix):`** The OpenAPI importer now appropriately brings in responses that are under the `text/event-stream`\
Content-Type if your endpoint is annotated with `x-fern-streaming`.\
If your endpoint is not annotated with `x-fern-streaming`, then the response will be ignored.\
\
\
# September 26, 2024\
\
## 0.43.2\
\
**`(fix):`** The CLI now prints which API cannot be registered if `fern generate --docs` fails.\
\
\
# September 25, 2024\
\
## 0.43.1\
\
**`(feat):`** The CLI now supports running OpenAPI generator 0.1.0 with IR version 53.\
\
\
# September 24, 2024\
\
## 0.43.0\
\
**`(feat):`** The CLI now recognizes the fern-php-sdk generator.\
\
\
# September 23, 2024\
\
## 0.42.15\
\
**`(internal):`** The documentation resolver now approrpiately creates a unique identifier for changelog sections. Previously, if you had multiple\
changelogs within the same section, despite their title and slug being different, they would be treated as the same section since the ID\
only took into account the parents' slug, appended the word "changelog" and that was all.\
\
As a result previously all changelogs within the same section would get highlighted when one was selected, now only the selected changelog\
is highlighted.\
\
\
# September 21, 2024\
\
## 0.42.14\
\
**`(fix):`** The OpenAPI importer now correctly propagates the title field on `oneof` schemas.\
\
\
# September 20, 2024\
\
## 0.42.12\
\
**`(fix):`** Previously, deploying docs from Windows machines led to bad asset paths.\
Now, the CLI respects Windows paths during run and web paths for retrieving\
assets.\
\
\
# September 19, 2024\
\
## 0.42.9\
\
**`(fix):`** Previously, the OpenAPI importer would ignore skip parsing arbitrary\
content types "*/*". Now it treats this content type as application/json.\
\
```json openapi.json\
"responses": \{\
  "200": \{\
    "description": "Success reply",\
    "content": \{\
      "*/*": \{\
```\
\
\
# September 18, 2024\
\
## 0.42.2\
\
**`(fix):`** Error bodies are now appropriately namespaced as well!\
\
\
# September 17, 2024\
\
## 0.41.15\
\
**`(internal):`** Performance improvements for stringifiying large Intermediate Representations. If\
you have a large OpenAPI spec or Fern Definition, this can potentially shave off\
minutes from `fern generate`.\
\
\
# September 16, 2024\
\
## 0.42.0-rc0\
\
**`(feat):`** The Fern Definition now supports `conten-type` on multipart request properties.\
For example, to specify an `application/octet-stream` and `application/json`\
contnet types, use the snippet below:\
\
```ts\
service:\
  endpoints:\
    upload:\
      request:\
        body:\
          properties:\
            file:\
              type: file\
              content-type: application/octet-stream\
            metadata:\
              type: unknown\
              content-type: application/json\
```\
\
\
# September 15, 2024\
\
## 0.41.14-rc1\
\
**`(feat):`** Running `fern check` will now check to confirm that the generator versions you are running are compatible with your Fern CLI version.\
\
Each version of SDK generators depends on a version of a libary that is exported by the Fern CLI, and as a result, each generator has a minimum\
compatible version of the Fern CLI. As an example, if you were to run `fern check` while leveraging `fernapi/fern-python-sdk` version `2.0.0`, on CLI version `0.1.3`, you'd receive the following error:\
\
`The generator fernapi/fern-python-sdk requires CLI version 0.23.0-rc4 or later (current version: 0.1.3-rc0).`\
\
Indicating that you must upgrade your CLI in order to leverage the current generator.\
\
### What's new\
\
* Running `fern check` will now check to confirm that the generator versions you are running are compatible with your Fern CLI version.\
* Fern commands now print out generator upgrades, in addition to CLI upgrades.\
\
\
# September 14, 2024\
\
## 0.41.11\
\
**`(feat):`** Adds availability and display-names to discriminated union values. Now, in your docs, you can mark your union values\
with custom names and show their availability. You can do so by adding the following to your API definition:\
\
```yml\
MyUnionType:\
  union:\
    UnionValue1:\
      docs: The first union value\
      type: string\
      display-name: Union Value One\
      availability: beta\
    UnionValue2:\
      docs: The second union value\
      type: integer\
      display-name: Union Value Two\
      availability: deprecated\
```\
\
\
# September 11, 2024\
\
## 0.41.10\
\
**`(feat):`** Adds availability and display-names to discriminated union values. Now, in your docs, you can mark your union values\
with custom names and show their availability. You can do so by adding the following to your API definition:\
\
```yml\
MyUnionType:\
  union:\
    UnionValue1:\
      docs: The first union value\
      type: string\
      display-name: Union Value One\
      availability: beta\
    UnionValue2:\
      docs: The second union value\
      type: integer\
      display-name: Union Value Two\
      availability: deprecated\
```\
\
\
# September 10, 2024\
\
## 0.41.9\
\
**`(internal):`** Adds a `bundle-path` hidden parameter for `fern docs dev` for use with `fern-platform` testing. You can pass the\
path on the command line as an optional parameter.\
\
\
# September 9, 2024\
\
## 0.41.8\
\
**`(feat):`** The Fern generators.yml configuration now supports a new format for namespacing APIs for additional flexibility:\
\
```yml\
api:\
  specs:\
    - openapi: path/to/v1/openapi\
      overrides: path/to/v1/overrides\
      namespace: v1\
    - openapi: path/to/v2/openapi\
      overrides: path/to/v2/overrides\
      namespace: v2\
```\
\
Through namespacing your API, you can have multiple objects and endpoints with the same name across different namespaces. You can think of them\
as the equivalent to Python modules or TypeScript packages.\
\
\
# September 8, 2024\
\
## 0.41.7\
\
**`(fix):`** Previously we weren't always awaiting PostHog API calls directly. Now the CLI\
awaits these calls so that we can ensure that events are sent.\
\
\
# September 7, 2024\
\
## 0.41.6\
\
**`(feat):`** The Fern Docs CLI now supports OAuth 2.0 Client Credentials injection in API playgrounds.\
To enable this feature, you can define the OAuth Authorization Scheme in your API configuration,\
and enable the feature in your docs configuration.\
\
API configuration:\
\
```yml\
api:\
  auth-schemes:\
    OAuth:\
      scheme: oauth\
      type: client-credentials\
      get-token:\
        endpoint: endpoint.authorization\
```\
\
[More Information](https://buildwithfern.com/learn/api-definition/fern/authentication#oauth-client-credentials)\
\
Docs configuration:\
\
```yml\
navigation:\
  section: API Reference\
    playground:\
      oauth: true\
```\
\
[More Information](https://buildwithfern.com/learn/docs/api-references/customize-api-playground)\
\
\
# September 6, 2024\
\
## 0.41.3\
\
**`(feat):`** Allow referencing by method and path. For example, when configuring an\
oauth scheme you can now do:\
\
```oauth.yml\
auth-schemes:\
  OAuth:\
    scheme: oauth\
    type: client-credentials\
    get-token:\
      endpoint: POST /oauth/token\
api:\
  auth: OAuth\
```\
\
\
# September 5, 2024\
\
## 0.41.2\
\
**`(fix):`** Fixes an issue introduced in `0.41.1` that ignored server urls for docs generation.\
\
**`(feat):`** Adds a `auth-schemes` and `auth` block where you can override auth for an existing spec.\
See below:\
\
```generators.yml\
auth-schemes:\
  Oauth:\
    scheme: oauth\
    type: client-credentials\
    get-token:\
      endpoint: auth.get-token\
api:\
  auth: Oauth # overrides auth scheme\
  specs:\
    - openapi: path/to/openapi\
```\
\
\
# September 4, 2024\
\
## 0.41.0\
\
**`(feat):`** Adds generic object declarations to the fern definition. Now we can define generics and\
use them in alias declarations to minimize code duplication:\
\
```yml\
types:\
  GenericTest<T>:\
    properties:\
      value: T\
      other-value: string\
\
  GenericApplication:\
    type: GenericTest<string>\
```\
\
More information can be found here: [https://buildwithfern.com/learn/api-definition/fern/types#generics](https://buildwithfern.com/learn/api-definition/fern/types#generics).\
\
\
# September 3, 2024\
\
## 0.41.0-rc1\
\
**`(fix):`** Fix an issue where some postman environment variables (e.g. API key) were not substituted\
when running fern generate.\
\
\
# September 2, 2024\
\
## 0.40.3\
\
**`(fix):`** Now `fern generator upgrade` respects  the `--group` flag and only upgrades generators within a particular group.\
\
\
# August 28, 2024\
\
## 0.40.0\
\
**`(feat):`** Update the `fern generator upgrade` command to leverage the Generator registry API as opposed to Docker and dockerode.\
\
\
# August 25, 2024\
\
## 0.39.19\
\
**`(fix):`** The OpenAPI importer now appropriately generates examples for circular `oneOf` schemas.\
\
### What's been fixed\
\
* The OpenAPI importer now handles generating examples for referenced `oneOf` schemas. Previously, examples generation would fail.\
* The OpenAPI importer now handles generating examples for circular `oneOf` schemas. Previously, the\
  the converter would only default to generating examples for the first `oneOf` schema. If the first variant,\
  circularly referenced itself, this would make terminating the example impossible.\
  Now, the example generator tries every schema in order, guaranteeing that a termination condition will be\
  reached.\
\
\
# August 23, 2024\
\
## 0.39.17\
\
**`(fix):`** object declarations with extends and no properties now has examples propagating in the Docs and SDKs\
\
### What's been fixed\
\
* Previously, object declarations with extends and no properties did not have examples\
  propagating in the Docs and SDKs. The core issue was in IR generation which has now\
  been resolved.\
\
The following will now work as expected:\
\
```yaml\
types:\
\
  ObjectWithNoProperties:\
    extends:\
      - ParentA\
      - ParentB\
    examples:\
      - name: Default\
        value:\
          propertyFromParentA: foo\
          propertyFromParentB: bar\
```\
\
\
# August 22, 2024\
\
## 0.39.16\
\
**`(chore):`** Support running 0.2.x versions of the Postman Generator with IR V53 or above.\
\
\
# August 21, 2024\
\
## 0.39.13\
\
**`(fix):`** Generated examples in the Intermediate Representation not respect root level path parameter examples.\
\
### What's been fixed\
\
* Generated examples in the Intermediate Representation not respect root level path parameter examples. Previously, when ignored, this would result in invalid cURL examples in documentation.\
\
\
# August 20, 2024\
\
## 0.39.11\
\
**`(fix):`** The Fern CLI now handles parsing `x-fern-parameter-name` on path parameters in an OpenAPI spec.\
\
### What's been fixed\
\
* Fix: The Fern CLI now handles parsing `x-fern-parameter-name` on path parameters in an OpenAPI spec. For example,\
  if you want to rename a path parameter in the generated SDK, you can now do:\
\
```yml\
paths:\
  "/user":\
      get:\
      operationId: list_user\
      parameters:\
          - in: header\
          name: X-API-Version\
          x-fern-parameter-name: version\
          schema:\
              type: string\
          required: true\
```\
\
For more information, please check out the [docs](https://buildwithfern.com/learn/api-definition/openapi/extensions/parameter-names).\
\
\
# August 19, 2024\
\
## 0.39.9\
\
**`(chore):`** Release 0.39.9\
\
\
# August 18, 2024\
\
## 0.39.7\
\
**`(chore):`** ## What's Changed\
\
* (feature, csharp): Generate well-known types by @amckinney in [https://github.com/fern-api/fern/pull/4319](https://github.com/fern-api/fern/pull/4319)\
* fix: fix seed, move unit test to right CoreUtility by @RohinBhargava in [https://github.com/fern-api/fern/pull/4324](https://github.com/fern-api/fern/pull/4324)\
* fix(openapi): generate examples with latest schemas by @dsinghvi in [https://github.com/fern-api/fern/pull/4329](https://github.com/fern-api/fern/pull/4329)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.39.6...0.39.7](https://github.com/fern-api/fern/compare/0.39.6...0.39.7)\
\
\
# August 16, 2024\
\
## 0.39.6\
\
**`(chore):`** ## What's Changed\
\
* fix (ir): upgrade pydantic generator by @dsinghvi in [https://github.com/fern-api/fern/pull/4320](https://github.com/fern-api/fern/pull/4320)\
* fix(ir): autogenerate ir sdks on version bump by @dsinghvi in [https://github.com/fern-api/fern/pull/4321](https://github.com/fern-api/fern/pull/4321)\
* fix(python): upgrade ir sdk to handle null unknown types by @dsinghvi in [https://github.com/fern-api/fern/pull/4322](https://github.com/fern-api/fern/pull/4322)\
* fix: add names to form data files by @RohinBhargava in [https://github.com/fern-api/fern/pull/4323](https://github.com/fern-api/fern/pull/4323)\
* fix(docs): global path parameter examples are respected by @dsinghvi in [https://github.com/fern-api/fern/pull/4325](https://github.com/fern-api/fern/pull/4325)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.39.5...0.39.6](https://github.com/fern-api/fern/compare/0.39.5...0.39.6)\
\
\
# August 15, 2024\
\
## 0.39.4\
\
**`(chore):`** ## What's Changed\
\
* (fix): update ete test snapshots by @dsinghvi in [https://github.com/fern-api/fern/pull/4311](https://github.com/fern-api/fern/pull/4311)\
* bump Python generator versions by @armandobelardo in [https://github.com/fern-api/fern/pull/4308](https://github.com/fern-api/fern/pull/4308)\
* fix: add in asyncapi tagging with namespaces by @armandobelardo in [https://github.com/fern-api/fern/pull/4313](https://github.com/fern-api/fern/pull/4313)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.39.3...0.39.4](https://github.com/fern-api/fern/compare/0.39.3...0.39.4)\
\
\
# August 14, 2024\
\
## 0.39.2\
\
**`(chore):`** ## What's Changed\
\
* feat: allow namespacing an API from generators.yml by @armandobelardo in [https://github.com/fern-api/fern/pull/4290](https://github.com/fern-api/fern/pull/4290)\
* fix: unions with utils re-force update refs by @armandobelardo in [https://github.com/fern-api/fern/pull/4296](https://github.com/fern-api/fern/pull/4296)\
* (feature, csharp): Generate gRPC core utilities by @amckinney in [https://github.com/fern-api/fern/pull/4298](https://github.com/fern-api/fern/pull/4298)\
* Update publish-docs command post-migration by @armandobelardo in [https://github.com/fern-api/fern/pull/4300](https://github.com/fern-api/fern/pull/4300)\
* Run publish-docs.yml if it's updated by @armandobelardo in [https://github.com/fern-api/fern/pull/4301](https://github.com/fern-api/fern/pull/4301)\
* document redirects by @chdeskur in [https://github.com/fern-api/fern/pull/4299](https://github.com/fern-api/fern/pull/4299)\
* (docs): add to our Welcome page that this docs site is built with Fern by @dannysheridan in [https://github.com/fern-api/fern/pull/4307](https://github.com/fern-api/fern/pull/4307)\
* add information on regex redirects by @chdeskur in [https://github.com/fern-api/fern/pull/4306](https://github.com/fern-api/fern/pull/4306)\
* fix: read templated env vars in the docs generator config by @pujitm in [https://github.com/fern-api/fern/pull/4287](https://github.com/fern-api/fern/pull/4287)\
* improvement: improve `.dict` speed by limiting dict calls by @armandobelardo in [https://github.com/fern-api/fern/pull/4302](https://github.com/fern-api/fern/pull/4302)\
* improvement: python handles arrays of deep object query parameters by @armandobelardo in [https://github.com/fern-api/fern/pull/4304](https://github.com/fern-api/fern/pull/4304)\
* (fix): docs take into account global path params and now we add tests by @dsinghvi in [https://github.com/fern-api/fern/pull/4309](https://github.com/fern-api/fern/pull/4309)\
\
## New Contributors\
\
* @pujitm made their first contribution in [https://github.com/fern-api/fern/pull/4287](https://github.com/fern-api/fern/pull/4287)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.39.1...0.39.2](https://github.com/fern-api/fern/compare/0.39.1...0.39.2)\
\
\
# August 13, 2024\
\
## 0.38.1\
\
**`(chore):`** ## What's Changed\
\
* (feat, docs): add docs on `api.yml` and environment audiences by @dsinghvi in [https://github.com/fern-api/fern/pull/4292](https://github.com/fern-api/fern/pull/4292)\
* (fix): ir generation respects disable examples by @dsinghvi in [https://github.com/fern-api/fern/pull/4293](https://github.com/fern-api/fern/pull/4293)\
* (fix, python): check autogenerated examples before indexing by @dsinghvi in [https://github.com/fern-api/fern/pull/4294](https://github.com/fern-api/fern/pull/4294)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.38.0...0.38.1](https://github.com/fern-api/fern/compare/0.38.0...0.38.1)\
\
\
# August 12, 2024\
\
## 0.38.0-rc0\
\
**`(chore):`** ## What's Changed\
\
* (feat, python): move to ruff for formatting by @dsinghvi in [https://github.com/fern-api/fern/pull/4219](https://github.com/fern-api/fern/pull/4219)\
* improvement: improve discriminated union object naming by @armandobelardo in [https://github.com/fern-api/fern/pull/4243](https://github.com/fern-api/fern/pull/4243)\
* (feature): Add encoding and source nodes by @amckinney in [https://github.com/fern-api/fern/pull/4240](https://github.com/fern-api/fern/pull/4240)\
* (feat, cli): add `has-next-page` property to IR by @dsinghvi in [https://github.com/fern-api/fern/pull/4241](https://github.com/fern-api/fern/pull/4241)\
* feat (wip): add playground settings for API playground by @RohinBhargava in [https://github.com/fern-api/fern/pull/4245](https://github.com/fern-api/fern/pull/4245)\
* fix: remove wraps from fastapi validators by @armandobelardo in [https://github.com/fern-api/fern/pull/4246](https://github.com/fern-api/fern/pull/4246)\
* fix: make model\\_validator take kwargs by @armandobelardo in [https://github.com/fern-api/fern/pull/4247](https://github.com/fern-api/fern/pull/4247)\
* (feat): refactor how pagination properties are checked in `fern check` by @dsinghvi in [https://github.com/fern-api/fern/pull/4250](https://github.com/fern-api/fern/pull/4250)\
* (feature): Add support for x-fern-encoding by @amckinney in [https://github.com/fern-api/fern/pull/4249](https://github.com/fern-api/fern/pull/4249)\
* (chore): Remove fhir.json by @amckinney in [https://github.com/fern-api/fern/pull/4253](https://github.com/fern-api/fern/pull/4253)\
* c#, improvements: small improvements including marking files `internal` + client classes `partial` by @dcb6 in [https://github.com/fern-api/fern/pull/4248](https://github.com/fern-api/fern/pull/4248)\
* c#, improvement: Use `FluentAssertions` in unit tests by @dcb6 in [https://github.com/fern-api/fern/pull/4254](https://github.com/fern-api/fern/pull/4254)\
* (feat): wire through api workspaces to docs validator by @dsinghvi in [https://github.com/fern-api/fern/pull/4255](https://github.com/fern-api/fern/pull/4255)\
* (feat): upgrade to yarn v4 by @dsinghvi in [https://github.com/fern-api/fern/pull/4257](https://github.com/fern-api/fern/pull/4257)\
* c#, improvements: breaking change with several small improvements by @dcb6 in [https://github.com/fern-api/fern/pull/4260](https://github.com/fern-api/fern/pull/4260)\
* feat, python: add in true forward compat enums by @armandobelardo in [https://github.com/fern-api/fern/pull/4262](https://github.com/fern-api/fern/pull/4262)\
* (feature): Copy source files in seed tests by @amckinney in [https://github.com/fern-api/fern/pull/4258](https://github.com/fern-api/fern/pull/4258)\
* c#, improvement: use string response directly in generic exception by @dcb6 in [https://github.com/fern-api/fern/pull/4264](https://github.com/fern-api/fern/pull/4264)\
* (internal): `pnpm` migration by @dsinghvi in [https://github.com/fern-api/fern/pull/4261](https://github.com/fern-api/fern/pull/4261)\
* Remove old documentation references from README by @armandobelardo in [https://github.com/fern-api/fern/pull/4265](https://github.com/fern-api/fern/pull/4265)\
* Fix typo in pr-preview\\.mdx by @zachkirsch in [https://github.com/fern-api/fern/pull/4235](https://github.com/fern-api/fern/pull/4235)\
* (chore): Update pnpm-lock.yaml by @amckinney in [https://github.com/fern-api/fern/pull/4266](https://github.com/fern-api/fern/pull/4266)\
* (fix): run compile on every PR by @dsinghvi in [https://github.com/fern-api/fern/pull/4267](https://github.com/fern-api/fern/pull/4267)\
* (fix): live tests continue to work in the pnpm era by @dsinghvi in [https://github.com/fern-api/fern/pull/4268](https://github.com/fern-api/fern/pull/4268)\
* (chore): Remove all yarn files by @amckinney in [https://github.com/fern-api/fern/pull/4269](https://github.com/fern-api/fern/pull/4269)\
* (chore, ir): Use latest TypeScript generator by @amckinney in [https://github.com/fern-api/fern/pull/4271](https://github.com/fern-api/fern/pull/4271)\
* (chore, ruby): Remove ir-sdk from generator-commons by @amckinney in [https://github.com/fern-api/fern/pull/4272](https://github.com/fern-api/fern/pull/4272)\
* (fix): bump to 53.6.x by @dsinghvi in [https://github.com/fern-api/fern/pull/4273](https://github.com/fern-api/fern/pull/4273)\
* (fix): get seed working by deleting yarn ref by @dsinghvi in [https://github.com/fern-api/fern/pull/4274](https://github.com/fern-api/fern/pull/4274)\
* (feature, csharp): Write Protobuf dependencies in .csproj by @amckinney in [https://github.com/fern-api/fern/pull/4270](https://github.com/fern-api/fern/pull/4270)\
* c#, fix: fix type conflicts by @dcb6 in [https://github.com/fern-api/fern/pull/4244](https://github.com/fern-api/fern/pull/4244)\
* (fix): ir generation for examples is stable so that ete tests work by @dsinghvi in [https://github.com/fern-api/fern/pull/4276](https://github.com/fern-api/fern/pull/4276)\
* fix: add validation around selectable environments for playground settings by @RohinBhargava in [https://github.com/fern-api/fern/pull/4252](https://github.com/fern-api/fern/pull/4252)\
* (chore, csharp): Release 1.2.1 by @amckinney in [https://github.com/fern-api/fern/pull/4284](https://github.com/fern-api/fern/pull/4284)\
* (followup): add tests for playground validation messages by @dsinghvi in [https://github.com/fern-api/fern/pull/4283](https://github.com/fern-api/fern/pull/4283)\
* ir: add `shape` to `ExampleQueryParameter` by @dcb6 in [https://github.com/fern-api/fern/pull/4222](https://github.com/fern-api/fern/pull/4222)\
* (fix): eslint is now a required check and will pass by @dsinghvi in [https://github.com/fern-api/fern/pull/4285](https://github.com/fern-api/fern/pull/4285)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.37.16...0.38.0-rc0](https://github.com/fern-api/fern/compare/0.37.16...0.38.0-rc0)\
\
\
# August 9, 2024\
\
## 0.37.16\
\
**`(chore):`** ## What's Changed\
\
* fix, python: make circular references more robust by @armandobelardo in [https://github.com/fern-api/fern/pull/4216](https://github.com/fern-api/fern/pull/4216)\
* improvement: allow naming for asyncapi messages to pull message name by @armandobelardo in [https://github.com/fern-api/fern/pull/4228](https://github.com/fern-api/fern/pull/4228)\
* c#, fix: class names + namespace conflicts by @dcb6 in [https://github.com/fern-api/fern/pull/4229](https://github.com/fern-api/fern/pull/4229)\
* Add support for anonymous usage of the generate CLI by @antoniomdk in [https://github.com/fern-api/fern/pull/4239](https://github.com/fern-api/fern/pull/4239)\
* (fix, docs): filter referenced subpackages appropriately by @dsinghvi in [https://github.com/fern-api/fern/pull/4242](https://github.com/fern-api/fern/pull/4242)\
\
## New Contributors\
\
* @antoniomdk made their first contribution in [https://github.com/fern-api/fern/pull/4239](https://github.com/fern-api/fern/pull/4239)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.37.15...0.37.16](https://github.com/fern-api/fern/compare/0.37.15...0.37.16)\
\
\
# August 8, 2024\
\
## 0.37.14-rc0\
\
**`(chore):`** ## What's Changed\
\
* fix: address TS UT fetcher flakiness by @RohinBhargava in [https://github.com/fern-api/fern/pull/4226](https://github.com/fern-api/fern/pull/4226)\
* chore: bump ir sdk to new Python generator by @armandobelardo in [https://github.com/fern-api/fern/pull/4214](https://github.com/fern-api/fern/pull/4214)\
* feat: hide TOC on docs home page by @zachkirsch in [https://github.com/fern-api/fern/pull/4230](https://github.com/fern-api/fern/pull/4230)\
* (fix, go): Required properties don't specify omitempty by @amckinney in [https://github.com/fern-api/fern/pull/4231](https://github.com/fern-api/fern/pull/4231)\
* (feat, in progress): ir supports user agent headers by @dsinghvi in [https://github.com/fern-api/fern/pull/4232](https://github.com/fern-api/fern/pull/4232)\
* (fix): LaTeX by @abvthecity in [https://github.com/fern-api/fern/pull/4233](https://github.com/fern-api/fern/pull/4233)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.37.13...0.37.14-rc0](https://github.com/fern-api/fern/compare/0.37.13...0.37.14-rc0)\
\
\
# August 7, 2024\
\
## 0.37.11\
\
**`(chore):`** ## What's Changed\
\
* Fix issue where misconfigured directory could cause unhelpful error message by @abarrell in [https://github.com/fern-api/fern/pull/4206](https://github.com/fern-api/fern/pull/4206)\
\
## New Contributors\
\
* @abarrell made their first contribution in [https://github.com/fern-api/fern/pull/4206](https://github.com/fern-api/fern/pull/4206)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.37.10...0.37.11](https://github.com/fern-api/fern/compare/0.37.10...0.37.11)\
\
\
# August 6, 2024\
\
## 0.37.7\
\
**`(chore):`** ## What's Changed\
\
* fix: python readme generation regression by @armandobelardo in [https://github.com/fern-api/fern/pull/4193](https://github.com/fern-api/fern/pull/4193)\
* fix, python: allow extending alias types by @armandobelardo in [https://github.com/fern-api/fern/pull/4190](https://github.com/fern-api/fern/pull/4190)\
* (internal): setup flamegraph generation for python generator by @dsinghvi in [https://github.com/fern-api/fern/pull/4196](https://github.com/fern-api/fern/pull/4196)\
* fix, python: Optional and aliased literals are populated in snippets by @armandobelardo in [https://github.com/fern-api/fern/pull/4184](https://github.com/fern-api/fern/pull/4184)\
* (feat, python): upgrade python generator to pydantic v2 by @dsinghvi in [https://github.com/fern-api/fern/pull/4197](https://github.com/fern-api/fern/pull/4197)\
* fix: add async iterable symbol to Stream Wrapper implementations by @RohinBhargava in [https://github.com/fern-api/fern/pull/4195](https://github.com/fern-api/fern/pull/4195)\
* feat: environment filter by audience by @RohinBhargava in [https://github.com/fern-api/fern/pull/4187](https://github.com/fern-api/fern/pull/4187)\
* (feat, python): use ruff for formatting by @dsinghvi in [https://github.com/fern-api/fern/pull/4199](https://github.com/fern-api/fern/pull/4199)\
* Revert "(feat, python): use ruff for formatting" by @dsinghvi in [https://github.com/fern-api/fern/pull/4200](https://github.com/fern-api/fern/pull/4200)\
* fix, python + ts: additional template bugs by @armandobelardo in [https://github.com/fern-api/fern/pull/4198](https://github.com/fern-api/fern/pull/4198)\
* fix: remove reserved properties from function signatures by @armandobelardo in [https://github.com/fern-api/fern/pull/4205](https://github.com/fern-api/fern/pull/4205)\
* fix, ir-generation: put fully substituted path in `url` field of auto-generated `EndpointExampleCall`s by @dcb6 in [https://github.com/fern-api/fern/pull/4211](https://github.com/fern-api/fern/pull/4211)\
* fix, python: allow typing any to be wrapped in optional to match Pydantic v2 by @armandobelardo in [https://github.com/fern-api/fern/pull/4203](https://github.com/fern-api/fern/pull/4203)\
* improvement: bring back wrapped aliases and custom root validators in\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/4204](https://github.com/fern-api/fern/pull/4204)\
* fix: typehinting on unions with visitors has been corrected by @armandobelardo in [https://github.com/fern-api/fern/pull/4213](https://github.com/fern-api/fern/pull/4213)\
* Update speakeasy.mdx by @dannysheridan in [https://github.com/fern-api/fern/pull/4215](https://github.com/fern-api/fern/pull/4215)\
* improvement: allow pydantic generator to specify package name by @armandobelardo in [https://github.com/fern-api/fern/pull/4217](https://github.com/fern-api/fern/pull/4217)\
* (feature): Add Protobuf mapper types by @amckinney in [https://github.com/fern-api/fern/pull/4210](https://github.com/fern-api/fern/pull/4210)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.37.6...0.37.7](https://github.com/fern-api/fern/compare/0.37.6...0.37.7)\
\
\
# August 2, 2024\
\
## 0.37.6\
\
**`(chore):`** ## What's Changed\
\
* fix: add literal properties back to typeddict snippets by @armandobelardo in [https://github.com/fern-api/fern/pull/4173](https://github.com/fern-api/fern/pull/4173)\
* (fix, typescript): wire `noScripts` into a PersistedProject and introduce a test by @dsinghvi in [https://github.com/fern-api/fern/pull/4185](https://github.com/fern-api/fern/pull/4185)\
* (feat, fastapi): introduce endpoint specific async handlers in fastapi by @dsinghvi in [https://github.com/fern-api/fern/pull/4188](https://github.com/fern-api/fern/pull/4188)\
* fix: python readme references request options correctly by @armandobelardo in [https://github.com/fern-api/fern/pull/4189](https://github.com/fern-api/fern/pull/4189)\
* fix: replace referenced markdown by @abvthecity in [https://github.com/fern-api/fern/pull/4191](https://github.com/fern-api/fern/pull/4191)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.37.5...0.37.6](https://github.com/fern-api/fern/compare/0.37.5...0.37.6)\
\
\
# August 1, 2024\
\
## 0.37.2\
\
**`(chore):`** ## What's Changed\
\
* (feature, csharp): Add RequestOptions by @amckinney in [https://github.com/fern-api/fern/pull/4166](https://github.com/fern-api/fern/pull/4166)\
* c#, improvement: error parsing  by @dcb6 in [https://github.com/fern-api/fern/pull/4168](https://github.com/fern-api/fern/pull/4168)\
* (fix): introduce extended properties into the IR by @dsinghvi in [https://github.com/fern-api/fern/pull/4171](https://github.com/fern-api/fern/pull/4171)\
* fix: OSS workspace settings propogate to APIs with dependencies by @armandobelardo in [https://github.com/fern-api/fern/pull/4147](https://github.com/fern-api/fern/pull/4147)\
* chore, python: generate union v2 templates by @armandobelardo in [https://github.com/fern-api/fern/pull/4167](https://github.com/fern-api/fern/pull/4167)\
* c# improvement: text responses + inlined request body inheritance by @dcb6 in [https://github.com/fern-api/fern/pull/4172](https://github.com/fern-api/fern/pull/4172)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.37.1...0.37.2](https://github.com/fern-api/fern/compare/0.37.1...0.37.2)\
\
\
# July 31, 2024\
\
## 0.37.0\
\
**`(chore):`** ## What's Changed\
\
* chore: bump typescript version and changelog by @RohinBhargava in [https://github.com/fern-api/fern/pull/4143](https://github.com/fern-api/fern/pull/4143)\
* feat: introduce typeddicts for request objects by @armandobelardo in [https://github.com/fern-api/fern/pull/4113](https://github.com/fern-api/fern/pull/4113)\
* fix, python: get api error through external import by @armandobelardo in [https://github.com/fern-api/fern/pull/4145](https://github.com/fern-api/fern/pull/4145)\
* fix: Fix unit test path and add CI check for this by @RohinBhargava in [https://github.com/fern-api/fern/pull/4148](https://github.com/fern-api/fern/pull/4148)\
* \\[c#, improvement]: add explicit namespaces to custom config by @dcb6 in [https://github.com/fern-api/fern/pull/4144](https://github.com/fern-api/fern/pull/4144)\
* c#, improvement: `set` instead of `init` field accessors in types by @dcb6 in [https://github.com/fern-api/fern/pull/4151](https://github.com/fern-api/fern/pull/4151)\
* (feature): Add IRv53; float type by @amckinney in [https://github.com/fern-api/fern/pull/4146](https://github.com/fern-api/fern/pull/4146)\
* c#, improvement: make datetime deserialization more lenient + include millis in datetime serialization by @dcb6 in [https://github.com/fern-api/fern/pull/4149](https://github.com/fern-api/fern/pull/4149)\
* chore: ci workflow gating on ts-sdk changes by @RohinBhargava in [https://github.com/fern-api/fern/pull/4152](https://github.com/fern-api/fern/pull/4152)\
* (fix, csharp): `map<string, unknown>` values are nullable by @amckinney in [https://github.com/fern-api/fern/pull/4153](https://github.com/fern-api/fern/pull/4153)\
* fix: incorrect code block indentation in api-yml.mdx by @abvthecity in [https://github.com/fern-api/fern/pull/4158](https://github.com/fern-api/fern/pull/4158)\
* (feature, csharp): Add support for allow-multiple query params by @amckinney in [https://github.com/fern-api/fern/pull/4157](https://github.com/fern-api/fern/pull/4157)\
* internal: update IR to have the FDR API definition ID by @armandobelardo in [https://github.com/fern-api/fern/pull/4161](https://github.com/fern-api/fern/pull/4161)\
* (feature, csharp): Support uint, ulong, and float by @amckinney in [https://github.com/fern-api/fern/pull/4160](https://github.com/fern-api/fern/pull/4160)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.36.0...0.37.0](https://github.com/fern-api/fern/compare/0.36.0...0.37.0)\
\
\
# July 29, 2024\
\
## 0.36.0\
\
**`(chore):`** ## What's Changed\
\
* improvement, python: export the root client from the root init file by @armandobelardo in [https://github.com/fern-api/fern/pull/4111](https://github.com/fern-api/fern/pull/4111)\
* (feat): support multi url environments in C# by @dsinghvi in [https://github.com/fern-api/fern/pull/4120](https://github.com/fern-api/fern/pull/4120)\
* (fix, csharp): MultiUrl environments now compile by @dsinghvi in [https://github.com/fern-api/fern/pull/4121](https://github.com/fern-api/fern/pull/4121)\
* c#, improvement: Add header suppliers to `RawClient` constructor parameters by @dcb6 in [https://github.com/fern-api/fern/pull/4119](https://github.com/fern-api/fern/pull/4119)\
* (fix, csharp): uuids are now generated as strings by @dsinghvi in [https://github.com/fern-api/fern/pull/4122](https://github.com/fern-api/fern/pull/4122)\
* (fix): regenerate c# model snapshots by @dsinghvi in [https://github.com/fern-api/fern/pull/4123](https://github.com/fern-api/fern/pull/4123)\
* feat: header tabs by @abvthecity in [https://github.com/fern-api/fern/pull/4124](https://github.com/fern-api/fern/pull/4124)\
* java, fix: match java local config to publish config by @dcb6 in [https://github.com/fern-api/fern/pull/4127](https://github.com/fern-api/fern/pull/4127)\
* follow up: release java sdk 1.0.5 by @dcb6 in [https://github.com/fern-api/fern/pull/4129](https://github.com/fern-api/fern/pull/4129)\
* fix: Add Stream Wrappers for use with various environments by @RohinBhargava in [https://github.com/fern-api/fern/pull/4118](https://github.com/fern-api/fern/pull/4118)\
* chore: add changelog and version for stream wrapper polyfill by @RohinBhargava in [https://github.com/fern-api/fern/pull/4130](https://github.com/fern-api/fern/pull/4130)\
* feat: enable arbitrary code snippets in docs by @abvthecity in [https://github.com/fern-api/fern/pull/4131](https://github.com/fern-api/fern/pull/4131)\
* fix: add start stream on pipe by @RohinBhargava in [https://github.com/fern-api/fern/pull/4132](https://github.com/fern-api/fern/pull/4132)\
* GH Workflow for Checking Generator Version Consistency by @dcb6 in [https://github.com/fern-api/fern/pull/4133](https://github.com/fern-api/fern/pull/4133)\
* fix: updated stream wrapper test paths by @RohinBhargava in [https://github.com/fern-api/fern/pull/4134](https://github.com/fern-api/fern/pull/4134)\
* fix: SSE Streaming Bifurcation by @RohinBhargava in [https://github.com/fern-api/fern/pull/4136](https://github.com/fern-api/fern/pull/4136)\
* (fix): global headers case insensitive comparison by @dsinghvi in [https://github.com/fern-api/fern/pull/4137](https://github.com/fern-api/fern/pull/4137)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.35.0...0.36.0](https://github.com/fern-api/fern/compare/0.35.0...0.36.0)\
\
\
# July 26, 2024\
\
## 0.36.0-rc0\
\
**`(chore):`** ## What's Changed\
\
* improvement, python: export the root client from the root init file by @armandobelardo in [https://github.com/fern-api/fern/pull/4111](https://github.com/fern-api/fern/pull/4111)\
* (feat): support multi url environments in C# by @dsinghvi in [https://github.com/fern-api/fern/pull/4120](https://github.com/fern-api/fern/pull/4120)\
* (fix, csharp): MultiUrl environments now compile by @dsinghvi in [https://github.com/fern-api/fern/pull/4121](https://github.com/fern-api/fern/pull/4121)\
* c#, improvement: Add header suppliers to `RawClient` constructor parameters by @dcb6 in [https://github.com/fern-api/fern/pull/4119](https://github.com/fern-api/fern/pull/4119)\
* (fix, csharp): uuids are now generated as strings by @dsinghvi in [https://github.com/fern-api/fern/pull/4122](https://github.com/fern-api/fern/pull/4122)\
* (fix): regenerate c# model snapshots by @dsinghvi in [https://github.com/fern-api/fern/pull/4123](https://github.com/fern-api/fern/pull/4123)\
* feat: header tabs by @abvthecity in [https://github.com/fern-api/fern/pull/4124](https://github.com/fern-api/fern/pull/4124)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.35.0...0.36.0-rc0](https://github.com/fern-api/fern/compare/0.35.0...0.36.0-rc0)\
\
\
# July 25, 2024\
\
## 0.35.0\
\
**`(chore):`** ## What's Changed\
\
* (feat): support `default-url`  and  url override on imports by @dsinghvi in [https://github.com/fern-api/fern/pull/4116](https://github.com/fern-api/fern/pull/4116)\
* (fix, openapi): set unauthed appropriately in openapi parser by @dsinghvi in [https://github.com/fern-api/fern/pull/4117](https://github.com/fern-api/fern/pull/4117)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.34.0...0.35.0](https://github.com/fern-api/fern/compare/0.34.0...0.35.0)\
\
\
# July 24, 2024\
\
## 0.33.6-rc0\
\
**`(chore):`** ## What's Changed\
\
* (chore): add SEO frontmatter section by @chdeskur in [https://github.com/fern-api/fern/pull/4101](https://github.com/fern-api/fern/pull/4101)\
* fix: update typing of `expected_types` to tuple to satisfy mypy by @armandobelardo in [https://github.com/fern-api/fern/pull/4100](https://github.com/fern-api/fern/pull/4100)\
* (chore): document nuget api key by @chdeskur in [https://github.com/fern-api/fern/pull/4103](https://github.com/fern-api/fern/pull/4103)\
* (chore): pypi styling update by @chdeskur in [https://github.com/fern-api/fern/pull/4105](https://github.com/fern-api/fern/pull/4105)\
* c#, improvement: datetime serialization by @dcb6 in [https://github.com/fern-api/fern/pull/4106](https://github.com/fern-api/fern/pull/4106)\
* feat: disable batch/stream toggle by @abvthecity in [https://github.com/fern-api/fern/pull/4108](https://github.com/fern-api/fern/pull/4108)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.33.5...0.33.6-rc0](https://github.com/fern-api/fern/compare/0.33.5...0.33.6-rc0)\
\
\
# July 23, 2024\
\
## 0.33.5\
\
**`(chore):`** ## What's Changed\
\
* (fix, go): Fix error handling for property-name error discrimination by @amckinney in [https://github.com/fern-api/fern/pull/4098](https://github.com/fern-api/fern/pull/4098)\
* improvement: support pydantic v2 outright by @armandobelardo in [https://github.com/fern-api/fern/pull/3805](https://github.com/fern-api/fern/pull/3805)\
* fix: int64 format is correctly parsed to long by @armandobelardo in [https://github.com/fern-api/fern/pull/4099](https://github.com/fern-api/fern/pull/4099)\
* c#, fix: fix datetime serialization, stop generating empty serialization unit tests by @dcb6 in [https://github.com/fern-api/fern/pull/4097](https://github.com/fern-api/fern/pull/4097)\
* \\[FER-2339] Pass OpenAPI request parameter examples through Fern IR Schema examples by @RohinBhargava in [https://github.com/fern-api/fern/pull/4095](https://github.com/fern-api/fern/pull/4095)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.33.4...0.33.5](https://github.com/fern-api/fern/compare/0.33.4...0.33.5)\
\
\
# July 22, 2024\
\
## 0.33.4\
\
**`(chore):`** ## What's Changed\
\
* adding readme alternative page by @chdeskur in [https://github.com/fern-api/fern/pull/4091](https://github.com/fern-api/fern/pull/4091)\
* fix: the ruby SDK now returns the parsed json instead of openstruct if no JSON serializer is specified by @armandobelardo in [https://github.com/fern-api/fern/pull/4092](https://github.com/fern-api/fern/pull/4092)\
* (fix): OpenAPI parser handles generating examples when no request or response required by @dsinghvi in [https://github.com/fern-api/fern/pull/4096](https://github.com/fern-api/fern/pull/4096)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.33.3...0.33.4](https://github.com/fern-api/fern/compare/0.33.3...0.33.4)\
\
\
# July 21, 2024\
\
## 0.33.3\
\
**`(chore):`** ## What's Changed\
\
* feat, csharp: Unit Test Generation + IR Bump  by @dcb6 in [https://github.com/fern-api/fern/pull/4047](https://github.com/fern-api/fern/pull/4047)\
* (fix): remove `jest-specific-snapshot` by @dsinghvi in [https://github.com/fern-api/fern/pull/4088](https://github.com/fern-api/fern/pull/4088)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.33.2...0.33.3](https://github.com/fern-api/fern/compare/0.33.2...0.33.3)\
\
\
# July 19, 2024\
\
## 0.33.2-rc0\
\
**`(chore):`** ## What's Changed\
\
* fix, python: only check the oauth expiry if there is a specified field by @armandobelardo in [https://github.com/fern-api/fern/pull/4077](https://github.com/fern-api/fern/pull/4077)\
* fix: python now requires an environment be specified if a default is not provided by @armandobelardo in [https://github.com/fern-api/fern/pull/4078](https://github.com/fern-api/fern/pull/4078)\
* (feat): support `fs.CreateReadStream` on Node 19+ form data uploads by @dsinghvi in [https://github.com/fern-api/fern/pull/4073](https://github.com/fern-api/fern/pull/4073)\
* (fix): support audiences on query parameters by @dsinghvi in [https://github.com/fern-api/fern/pull/4067](https://github.com/fern-api/fern/pull/4067)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.33.1...0.33.2-rc0](https://github.com/fern-api/fern/compare/0.33.1...0.33.2-rc0)\
\
\
# July 17, 2024\
\
## 0.33.0\
\
**`(chore):`** ## What's Changed\
\
* fix: python sdk serializes bytes within JSON by @armandobelardo in [https://github.com/fern-api/fern/pull/4070](https://github.com/fern-api/fern/pull/4070)\
* (fix, typescript): multipart form upload on Node 19+ by @dsinghvi in [https://github.com/fern-api/fern/pull/4056](https://github.com/fern-api/fern/pull/4056)\
* (feat): `ir` now adds a `TypeReference` for container types that makes it easier to generate snippets + autogenerated type examples by @dsinghvi in [https://github.com/fern-api/fern/pull/4038](https://github.com/fern-api/fern/pull/4038)\
* (fix): fix `ir-sdk-latest` `generators.yml` by @dcb6 in [https://github.com/fern-api/fern/pull/4074](https://github.com/fern-api/fern/pull/4074)\
* (feature, typescript): Generarte API version scheme by @amckinney in [https://github.com/fern-api/fern/pull/4071](https://github.com/fern-api/fern/pull/4071)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.32.0...0.33.0](https://github.com/fern-api/fern/compare/0.32.0...0.33.0)\
\
\
# July 16, 2024\
\
## 0.32.0\
\
**`(chore):`** ## What's Changed\
\
* (fix, openapi): Resolve 'refs' specified in overrides by @amckinney in [https://github.com/fern-api/fern/pull/4049](https://github.com/fern-api/fern/pull/4049)\
* Initial Swift Codegen by @armandobelardo in [https://github.com/fern-api/fern/pull/4035](https://github.com/fern-api/fern/pull/4035)\
* (fix): Swift generator and template by @amckinney in [https://github.com/fern-api/fern/pull/4050](https://github.com/fern-api/fern/pull/4050)\
* fix: ignore data urls in parseImagePaths by @abvthecity in [https://github.com/fern-api/fern/pull/4053](https://github.com/fern-api/fern/pull/4053)\
* (feature, typescript): Add omitUndefined option by @amckinney in [https://github.com/fern-api/fern/pull/4052](https://github.com/fern-api/fern/pull/4052)\
* docs: Inspiration from Conjure, Smithy, and Stripe Docs by @dannysheridan in [https://github.com/fern-api/fern/pull/4054](https://github.com/fern-api/fern/pull/4054)\
* feature: add Penguin AI and Koala to our docs website by @dannysheridan in [https://github.com/fern-api/fern/pull/3962](https://github.com/fern-api/fern/pull/3962)\
* (fix): eslint works by @dsinghvi in [https://github.com/fern-api/fern/pull/4055](https://github.com/fern-api/fern/pull/4055)\
* fix: python snippet and template recursion errors by @armandobelardo in [https://github.com/fern-api/fern/pull/4057](https://github.com/fern-api/fern/pull/4057)\
* (feature, typescript): Use generator-cli to generate reference.md by @amckinney in [https://github.com/fern-api/fern/pull/4062](https://github.com/fern-api/fern/pull/4062)\
* fix: analytics scripts by @abvthecity in [https://github.com/fern-api/fern/pull/4063](https://github.com/fern-api/fern/pull/4063)\
* fix analytics 2 by @abvthecity in [https://github.com/fern-api/fern/pull/4064](https://github.com/fern-api/fern/pull/4064)\
* fix: fern docs publishing by @abvthecity in [https://github.com/fern-api/fern/pull/4065](https://github.com/fern-api/fern/pull/4065)\
* feature: add tracking via rb2b by @dannysheridan in [https://github.com/fern-api/fern/pull/4061](https://github.com/fern-api/fern/pull/4061)\
* chore: add back x-readme code samples by @armandobelardo in [https://github.com/fern-api/fern/pull/4060](https://github.com/fern-api/fern/pull/4060)\
* (feature): Add ApiVersionSchema type by @amckinney in [https://github.com/fern-api/fern/pull/4068](https://github.com/fern-api/fern/pull/4068)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.24...0.32.0](https://github.com/fern-api/fern/compare/0.31.24...0.32.0)\
\
\
# July 12, 2024\
\
## 0.31.24\
\
**`(chore):`** Release 0.31.24\
\
\
# July 11, 2024\
\
## 0.31.23-rc0\
\
**`(chore):`** ## What's Changed\
\
* (feature, typescript): Add setObjectProperty core utility by @amckinney in [https://github.com/fern-api/fern/pull/4032](https://github.com/fern-api/fern/pull/4032)\
* c#, fix: increase supported union size + handle double optionals by @dcb6 in [https://github.com/fern-api/fern/pull/4033](https://github.com/fern-api/fern/pull/4033)\
* (fix): Handle circular references in serialization layer by @amckinney in [https://github.com/fern-api/fern/pull/4036](https://github.com/fern-api/fern/pull/4036)\
* fix: fastapi generation does not duplicate descriptions anymore by @armandobelardo in [https://github.com/fern-api/fern/pull/4037](https://github.com/fern-api/fern/pull/4037)\
* (feat): ir now adds a TypeReference for container types that makes it easier to generate snippets by @dcb6 in [https://github.com/fern-api/fern/pull/4038](https://github.com/fern-api/fern/pull/4038)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.22...0.31.23-rc0](https://github.com/fern-api/fern/compare/0.31.22...0.31.23-rc0)\
\
\
# July 10, 2024\
\
## 0.31.22\
\
**`(chore):`** ## What's Changed\
\
* Revert "Revert "feat: landing page in docs"" by @abvthecity in [https://github.com/fern-api/fern/pull/4023](https://github.com/fern-api/fern/pull/4023)\
* Fix core-utilities typescript tests by @williamluer in [https://github.com/fern-api/fern/pull/4022](https://github.com/fern-api/fern/pull/4022)\
* experimental: scan files to include react in mdx by @abvthecity in [https://github.com/fern-api/fern/pull/4015](https://github.com/fern-api/fern/pull/4015)\
* (feat, typescript): make `zurg` completely synchronous by @dsinghvi in [https://github.com/fern-api/fern/pull/4024](https://github.com/fern-api/fern/pull/4024)\
* (chore): add xml type by @chdeskur in [https://github.com/fern-api/fern/pull/4025](https://github.com/fern-api/fern/pull/4025)\
* fix: (regression) parseDocsConfiguration accidentally calls loadAllPages with absolutePathToDocsConfig by @abvthecity in [https://github.com/fern-api/fern/pull/4026](https://github.com/fern-api/fern/pull/4026)\
* (feature, typescript): Add offset step pagination with IRv48 by @amckinney in [https://github.com/fern-api/fern/pull/4028](https://github.com/fern-api/fern/pull/4028)\
* csharp, fix, feature, improvment: Target .NET Standard + Framework, fix various bugs, many small improvements by @dcb6 in [https://github.com/fern-api/fern/pull/4030](https://github.com/fern-api/fern/pull/4030)\
* fix: update unchecked base model to not coerce none by @armandobelardo in [https://github.com/fern-api/fern/pull/4029](https://github.com/fern-api/fern/pull/4029)\
* fix: unreserve `set` name for python methods by @armandobelardo in [https://github.com/fern-api/fern/pull/4031](https://github.com/fern-api/fern/pull/4031)\
* add in swift to seed runner by @armandobelardo in [https://github.com/fern-api/fern/pull/4034](https://github.com/fern-api/fern/pull/4034)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.21...0.31.22](https://github.com/fern-api/fern/compare/0.31.21...0.31.22)\
\
\
# July 9, 2024\
\
## 0.31.18\
\
**`(chore):`** ## What's Changed\
\
* feat: landing page in docs by @abvthecity in [https://github.com/fern-api/fern/pull/3999](https://github.com/fern-api/fern/pull/3999)\
* (feature, typescript): Add support for alpha/beta dist tags by @amckinney in [https://github.com/fern-api/fern/pull/4000](https://github.com/fern-api/fern/pull/4000)\
* fix: allowed text encodings by @abvthecity in [https://github.com/fern-api/fern/pull/4005](https://github.com/fern-api/fern/pull/4005)\
* (internal): get ci to green by @dsinghvi in [https://github.com/fern-api/fern/pull/4009](https://github.com/fern-api/fern/pull/4009)\
* (feat, typescript): support jsr publish by @dsinghvi in [https://github.com/fern-api/fern/pull/4007](https://github.com/fern-api/fern/pull/4007)\
* (chore, python): Update README.md snapshots by @amckinney in [https://github.com/fern-api/fern/pull/4012](https://github.com/fern-api/fern/pull/4012)\
* (chore, check): Add pagination test cases by @amckinney in [https://github.com/fern-api/fern/pull/4011](https://github.com/fern-api/fern/pull/4011)\
* (fix, typescript): readme correctly displays advanced sections by @dsinghvi in [https://github.com/fern-api/fern/pull/4013](https://github.com/fern-api/fern/pull/4013)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.17...0.31.18-rc0](https://github.com/fern-api/fern/compare/0.31.17...0.31.18-rc0)\
\
\
# July 5, 2024\
\
## 0.31.15\
\
**`(chore):`** ## What's Changed\
\
* (chore): update availability.mdx by @chdeskur in [https://github.com/fern-api/fern/pull/3989](https://github.com/fern-api/fern/pull/3989)\
* (fix, openapi): Fix allOf object filtering by @amckinney in [https://github.com/fern-api/fern/pull/3990](https://github.com/fern-api/fern/pull/3990)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.14...0.31.15](https://github.com/fern-api/fern/compare/0.31.14...0.31.15)\
\
\
# July 4, 2024\
\
## 0.31.11\
\
**`(chore):`** ## What's Changed\
\
* fix: ruby snippets for dates have correct quotes by @armandobelardo in [https://github.com/fern-api/fern/pull/3983](https://github.com/fern-api/fern/pull/3983)\
* improvement: python respects ir50, inserts defaults by @armandobelardo in [https://github.com/fern-api/fern/pull/3982](https://github.com/fern-api/fern/pull/3982)\
* (fix, openapi): Prefer security schemes in order by @amckinney in [https://github.com/fern-api/fern/pull/3984](https://github.com/fern-api/fern/pull/3984)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.10...0.31.11](https://github.com/fern-api/fern/compare/0.31.10...0.31.11)\
\
\
# July 3, 2024\
\
## 0.31.10\
\
**`(chore):`** ## What's Changed\
\
* improvement: add advanced section to python readme by @armandobelardo in [https://github.com/fern-api/fern/pull/3970](https://github.com/fern-api/fern/pull/3970)\
* (feat): customize status code for typescript express generator  by @dsinghvi in [https://github.com/fern-api/fern/pull/3971](https://github.com/fern-api/fern/pull/3971)\
* fix, python: allow offsets to start at 0 by @armandobelardo in [https://github.com/fern-api/fern/pull/3972](https://github.com/fern-api/fern/pull/3972)\
* fix: python pagination helper types now share generic type by @armandobelardo in [https://github.com/fern-api/fern/pull/3973](https://github.com/fern-api/fern/pull/3973)\
* chore: update python seed after generator-cli update by @armandobelardo in [https://github.com/fern-api/fern/pull/3974](https://github.com/fern-api/fern/pull/3974)\
* (charp, fix): Empty Root Client Methods + `.Core` namespace issue by @dcb6 in [https://github.com/fern-api/fern/pull/3975](https://github.com/fern-api/fern/pull/3975)\
* (java, improvement): change default `JsonInclude` behavior  by @dcb6 in [https://github.com/fern-api/fern/pull/3978](https://github.com/fern-api/fern/pull/3978)\
* (csharp, fix): base client requests not generated by @dcb6 in [https://github.com/fern-api/fern/pull/3976](https://github.com/fern-api/fern/pull/3976)\
* chore: plumb through ruby snippets config to FDR by @armandobelardo in [https://github.com/fern-api/fern/pull/3980](https://github.com/fern-api/fern/pull/3980)\
* improvement: allow boolean defaults within IR by @armandobelardo in [https://github.com/fern-api/fern/pull/3981](https://github.com/fern-api/fern/pull/3981)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.9...0.31.10](https://github.com/fern-api/fern/compare/0.31.9...0.31.10)\
\
\
# July 1, 2024\
\
## 0.31.8\
\
**`(chore):`** ## What's Changed\
\
* fix: generator upgrade cli upgrades in place by @armandobelardo in [https://github.com/fern-api/fern/pull/3951](https://github.com/fern-api/fern/pull/3951)\
* feat: add reviewers blocks to generators.yml by @armandobelardo in [https://github.com/fern-api/fern/pull/3952](https://github.com/fern-api/fern/pull/3952)\
* Use all FormData headers and don't stringify stream.Readable by @williamluer in [https://github.com/fern-api/fern/pull/3956](https://github.com/fern-api/fern/pull/3956)\
* (feat, csharp): support extra dependencies  by @dsinghvi in [https://github.com/fern-api/fern/pull/3957](https://github.com/fern-api/fern/pull/3957)\
* improvement: allow specifying if taking major in flag by @armandobelardo in [https://github.com/fern-api/fern/pull/3958](https://github.com/fern-api/fern/pull/3958)\
* fix: include css alongside js when validating UTF8 files by @abvthecity in [https://github.com/fern-api/fern/pull/3959](https://github.com/fern-api/fern/pull/3959)\
\
## New Contributors\
\
* @williamluer made their first contribution in [https://github.com/fern-api/fern/pull/3956](https://github.com/fern-api/fern/pull/3956)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.7...0.31.8](https://github.com/fern-api/fern/compare/0.31.7...0.31.8)\
\
\
# June 28, 2024\
\
## 0.31.7\
\
**`(chore):`** ## What's Changed\
\
* fix: validate files to be uploaded by @trevorblades in [https://github.com/fern-api/fern/pull/3917](https://github.com/fern-api/fern/pull/3917)\
* fix: python list allowlist is now case insensitive by @armandobelardo in [https://github.com/fern-api/fern/pull/3950](https://github.com/fern-api/fern/pull/3950)\
* improvement: add x-fern-base-path to asyncapi extensions by @armandobelardo in [https://github.com/fern-api/fern/pull/3953](https://github.com/fern-api/fern/pull/3953)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.6...0.31.7](https://github.com/fern-api/fern/compare/0.31.6...0.31.7)\
\
\
# June 27, 2024\
\
## 0.31.4\
\
**`(chore):`** ## What's Changed\
\
* (feat, typescript): support automatic cursor based pagination by @dsinghvi in [https://github.com/fern-api/fern/pull/3941](https://github.com/fern-api/fern/pull/3941)\
* (fix, typescript): auto pagination handles optional results arrays by @dsinghvi in [https://github.com/fern-api/fern/pull/3942](https://github.com/fern-api/fern/pull/3942)\
* (fix, openapi):  `x-fern-global-headers` works with predefined types by @dsinghvi in [https://github.com/fern-api/fern/pull/3943](https://github.com/fern-api/fern/pull/3943)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.3...0.31.4](https://github.com/fern-api/fern/compare/0.31.3...0.31.4)\
\
\
# June 26, 2024\
\
## 0.31.1\
\
**`(chore):`** ## What's Changed\
\
* fix: ruby RC respects header prefixes again by @armandobelardo in [https://github.com/fern-api/fern/pull/3927](https://github.com/fern-api/fern/pull/3927)\
* (feat, cli): add support for `--mode pull-request` in the CLI when running `fern generate` by @dsinghvi in [https://github.com/fern-api/fern/pull/3928](https://github.com/fern-api/fern/pull/3928)\
* fix, ruby: add one missed prefix fix by @armandobelardo in [https://github.com/fern-api/fern/pull/3929](https://github.com/fern-api/fern/pull/3929)\
* docs: add java example for oauth by @dcb6 in [https://github.com/fern-api/fern/pull/3930](https://github.com/fern-api/fern/pull/3930)\
* (improvement, python): add in root client templates for python snippets by @armandobelardo in [https://github.com/fern-api/fern/pull/3931](https://github.com/fern-api/fern/pull/3931)\
* Update generate-api-ref.mdx by @dannysheridan in [https://github.com/fern-api/fern/pull/3933](https://github.com/fern-api/fern/pull/3933)\
* improvement: add streaming and pagination sections to generated readme by @armandobelardo in [https://github.com/fern-api/fern/pull/3932](https://github.com/fern-api/fern/pull/3932)\
* java: make base api error class name configurable by @dcb6 in [https://github.com/fern-api/fern/pull/3934](https://github.com/fern-api/fern/pull/3934)\
* (chore, internal): upgrade python generator to use ir v49 by @dsinghvi in [https://github.com/fern-api/fern/pull/3915](https://github.com/fern-api/fern/pull/3915)\
* build(deps-dev): bump @types/jest-specific-snapshot from 0.5.7 to 0.5.9 by @dependabot in [https://github.com/fern-api/fern/pull/3925](https://github.com/fern-api/fern/pull/3925)\
* build(deps-dev): bump jsonc-parser from 2.2.1 to 3.3.0 by @dependabot in [https://github.com/fern-api/fern/pull/3924](https://github.com/fern-api/fern/pull/3924)\
* build(deps-dev): bump @types/is-ci from 3.0.2 to 3.0.4 by @dependabot in [https://github.com/fern-api/fern/pull/3922](https://github.com/fern-api/fern/pull/3922)\
* (fix, typescript): upgrade generators to `v46.2.0` by @dsinghvi in [https://github.com/fern-api/fern/pull/3935](https://github.com/fern-api/fern/pull/3935)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.0...0.31.1](https://github.com/fern-api/fern/compare/0.31.0...0.31.1)\
\
\
# June 24, 2024\
\
## 0.31.0-rc3\
\
**`(chore):`** ## What's Changed\
\
* (fix, python): SDK doesn't leak `JSONDecodeError` to users by @dsinghvi in [https://github.com/fern-api/fern/pull/3908](https://github.com/fern-api/fern/pull/3908)\
* (fix, python): python sdk generator handles stream termination like `[[DONE]]` by @dsinghvi in [https://github.com/fern-api/fern/pull/3909](https://github.com/fern-api/fern/pull/3909)\
* (feature, readme): Add support for configurable introduction by @amckinney in [https://github.com/fern-api/fern/pull/3898](https://github.com/fern-api/fern/pull/3898)\
* build(deps): bump ws from 8.17.0 to 8.17.1 by @dependabot in [https://github.com/fern-api/fern/pull/3866](https://github.com/fern-api/fern/pull/3866)\
* (internal, refactor): make `OSSWorkspace` and `FernWorkspace` classes by @dsinghvi in [https://github.com/fern-api/fern/pull/3910](https://github.com/fern-api/fern/pull/3910)\
* (refactor, internal): generate fern workspace before calling generate by @dsinghvi in [https://github.com/fern-api/fern/pull/3911](https://github.com/fern-api/fern/pull/3911)\
* (refactor, internal): clean up how OpenAPI parser deals with settings by @dsinghvi in [https://github.com/fern-api/fern/pull/3912](https://github.com/fern-api/fern/pull/3912)\
* (feat, cli): support customizing api settings per generator by @dsinghvi in [https://github.com/fern-api/fern/pull/3913](https://github.com/fern-api/fern/pull/3913)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.0-rc2...0.31.0-rc3](https://github.com/fern-api/fern/compare/0.31.0-rc2...0.31.0-rc3)\
\
\
# June 22, 2024\
\
## 0.31.0-rc1\
\
**`(chore):`** ## What's Changed\
\
* fix, ruby: leverage a types module by @armandobelardo in [https://github.com/fern-api/fern/pull/3893](https://github.com/fern-api/fern/pull/3893)\
* (fix, typescript): generate streaming endpoint snippets by @dsinghvi in [https://github.com/fern-api/fern/pull/3895](https://github.com/fern-api/fern/pull/3895)\
* fix: new ruby generator config matches class reference and class decl\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3896](https://github.com/fern-api/fern/pull/3896)\
* fix, python: readme is not specified in pyproject if not made by @armandobelardo in [https://github.com/fern-api/fern/pull/3894](https://github.com/fern-api/fern/pull/3894)\
* (fix, csharp): query params for datetimes index `Value` by @dsinghvi in [https://github.com/fern-api/fern/pull/3892](https://github.com/fern-api/fern/pull/3892)\
* (feature, python): Generate better README.md by @amckinney in [https://github.com/fern-api/fern/pull/3897](https://github.com/fern-api/fern/pull/3897)\
* (fix, typescript): remove fs dependency in browser runtimes by @dsinghvi in [https://github.com/fern-api/fern/pull/3899](https://github.com/fern-api/fern/pull/3899)\
* (fix, csharp): sdk respects service level path and path parameters by @dsinghvi in [https://github.com/fern-api/fern/pull/3900](https://github.com/fern-api/fern/pull/3900)\
* fix: validate files to be uploaded by @trevorblades in [https://github.com/fern-api/fern/pull/3872](https://github.com/fern-api/fern/pull/3872)\
* (feat, csharp): support sending bytes requests by @dsinghvi in [https://github.com/fern-api/fern/pull/3901](https://github.com/fern-api/fern/pull/3901)\
* (fix, csharp): safe join url and base path by @dsinghvi in [https://github.com/fern-api/fern/pull/3902](https://github.com/fern-api/fern/pull/3902)\
* Revert "fix: validate files to be uploaded" by @abvthecity in [https://github.com/fern-api/fern/pull/3904](https://github.com/fern-api/fern/pull/3904)\
* feat: changelog on tabs and sections by @abvthecity in [https://github.com/fern-api/fern/pull/3903](https://github.com/fern-api/fern/pull/3903)\
\
## New Contributors\
\
* @trevorblades made their first contribution in [https://github.com/fern-api/fern/pull/3872](https://github.com/fern-api/fern/pull/3872)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.31.0-rc0...0.31.0-rc1](https://github.com/fern-api/fern/compare/0.31.0-rc0...0.31.0-rc1)\
\
\
# June 20, 2024\
\
## 0.31.0-rc0\
\
**`(chore):`** ## What's Changed\
\
* (fix, csharp): revert to .NET 6+ compatibility by @dsinghvi in [https://github.com/fern-api/fern/pull/3882](https://github.com/fern-api/fern/pull/3882)\
* (fix, ts): Fix environment import in snippets by @amckinney in [https://github.com/fern-api/fern/pull/3885](https://github.com/fern-api/fern/pull/3885)\
* (feat, internal): setup csharp seed scripts by @dsinghvi in [https://github.com/fern-api/fern/pull/3884](https://github.com/fern-api/fern/pull/3884)\
* (feature, ts): Merge README.md files by @amckinney in [https://github.com/fern-api/fern/pull/3881](https://github.com/fern-api/fern/pull/3881)\
* (fix, csharp): ToString() Datetimes must be explicitly iso encoded by @dsinghvi in [https://github.com/fern-api/fern/pull/3886](https://github.com/fern-api/fern/pull/3886)\
* (feat, internal): run seed with audiences  by @dsinghvi in [https://github.com/fern-api/fern/pull/3887](https://github.com/fern-api/fern/pull/3887)\
* (fix, csharp): handle discriminated unions + header literal parameters by @dsinghvi in [https://github.com/fern-api/fern/pull/3888](https://github.com/fern-api/fern/pull/3888)\
* (fix, csharp): handle optional datetime encoding by @dsinghvi in [https://github.com/fern-api/fern/pull/3889](https://github.com/fern-api/fern/pull/3889)\
* (fix): add seed test case for optional datetime query parameters by @dsinghvi in [https://github.com/fern-api/fern/pull/3890](https://github.com/fern-api/fern/pull/3890)\
* (fix): remove sdk language toggle for new unions by @dsinghvi in [https://github.com/fern-api/fern/pull/3891](https://github.com/fern-api/fern/pull/3891)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.30.10...0.31.0-rc0](https://github.com/fern-api/fern/compare/0.30.10...0.31.0-rc0)\
\
\
# June 19, 2024\
\
## 0.30.9\
\
**`(chore):`** ## What's Changed\
\
* fix: bold text on \'93comparison with openapi\'94 docs by @zachkirsch in [https://github.com/fern-api/fern/pull/3876](https://github.com/fern-api/fern/pull/3876)\
* (fix, typescript): snippet templates include client import by @dsinghvi in [https://github.com/fern-api/fern/pull/3878](https://github.com/fern-api/fern/pull/3878)\
* (fix, ts): Update README.md snippets to call nested methods by @amckinney in [https://github.com/fern-api/fern/pull/3873](https://github.com/fern-api/fern/pull/3873)\
* fix: python and ts generators only add publish block if they have cre\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3871](https://github.com/fern-api/fern/pull/3871)\
* (fix, openapi): generate examples for discriminated unions by @dsinghvi in [https://github.com/fern-api/fern/pull/3879](https://github.com/fern-api/fern/pull/3879)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.30.8...0.30.9](https://github.com/fern-api/fern/compare/0.30.8...0.30.9)\
\
\
# June 18, 2024\
\
## 0.30.8-rc7\
\
**`(chore):`** ## What's Changed\
\
* fix: merge and filter children within non-visited subpackage by @abvthecity in [https://github.com/fern-api/fern/pull/3854](https://github.com/fern-api/fern/pull/3854)\
* (fix, docs): Update OAuth section by @amckinney in [https://github.com/fern-api/fern/pull/3856](https://github.com/fern-api/fern/pull/3856)\
* build(deps): bump idna from 3.6 to 3.7 in /generators/python by @dependabot in [https://github.com/fern-api/fern/pull/3364](https://github.com/fern-api/fern/pull/3364)\
* (fix, ts): Snippets and GitHub publish workflow by @amckinney in [https://github.com/fern-api/fern/pull/3858](https://github.com/fern-api/fern/pull/3858)\
* docs: fix broken links to cli commands by @atwooddc in [https://github.com/fern-api/fern/pull/3782](https://github.com/fern-api/fern/pull/3782)\
* docs: add openapi and asyncapi overrides by @dannysheridan in [https://github.com/fern-api/fern/pull/3863](https://github.com/fern-api/fern/pull/3863)\
* build(deps): bump @fern-fern/ir-v1-model from 0.0.1 to 0.0.2 by @dependabot in [https://github.com/fern-api/fern/pull/3861](https://github.com/fern-api/fern/pull/3861)\
* build(deps): bump @fern-fern/ir-v16-model from 0.0.1 to 0.0.4 by @dependabot in [https://github.com/fern-api/fern/pull/3860](https://github.com/fern-api/fern/pull/3860)\
* feat, ruby: enable oauth client generation by @armandobelardo in [https://github.com/fern-api/fern/pull/3842](https://github.com/fern-api/fern/pull/3842)\
* docs: add fern definition display-name property by @chdeskur in [https://github.com/fern-api/fern/pull/3864](https://github.com/fern-api/fern/pull/3864)\
* (feature, IRv48): Add offset pagination step by @amckinney in [https://github.com/fern-api/fern/pull/3865](https://github.com/fern-api/fern/pull/3865)\
* bump ir to account for ruby upgrade by @armandobelardo in [https://github.com/fern-api/fern/pull/3868](https://github.com/fern-api/fern/pull/3868)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.30.8-rc6...0.30.8-rc7](https://github.com/fern-api/fern/compare/0.30.8-rc6...0.30.8-rc7)\
\
\
# June 14, 2024\
\
## 0.30.8-rc0\
\
**`(chore):`** ## What's Changed\
\
* java, feature: pagination by @dcb6 in [https://github.com/fern-api/fern/pull/3845](https://github.com/fern-api/fern/pull/3845)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.30.7...0.30.8-rc0](https://github.com/fern-api/fern/compare/0.30.7...0.30.8-rc0)\
\
\
# June 13, 2024\
\
## 0.30.5\
\
**`(chore):`** ## What's Changed\
\
* (fix, go): Handle deepObject query parameter arrays by @amckinney in [https://github.com/fern-api/fern/pull/3836](https://github.com/fern-api/fern/pull/3836)\
* \\[FER-1986] Fix two DiscriminatedUnion bugs in dynamic Typescript snippets by @ppod1991 in [https://github.com/fern-api/fern/pull/3833](https://github.com/fern-api/fern/pull/3833)\
* added custom package json config by @jmedway614 in [https://github.com/fern-api/fern/pull/3832](https://github.com/fern-api/fern/pull/3832)\
* (release, typescript): version `0.23.0-rc1` by @dsinghvi in [https://github.com/fern-api/fern/pull/3838](https://github.com/fern-api/fern/pull/3838)\
* (fix, ts): Support README.md generation in local mode by @amckinney in [https://github.com/fern-api/fern/pull/3839](https://github.com/fern-api/fern/pull/3839)\
* Chdeskur/streamline audiences by @chdeskur in [https://github.com/fern-api/fern/pull/3815](https://github.com/fern-api/fern/pull/3815)\
* Bump boxen from 7.0.0 to 7.1.1 by @dependabot in [https://github.com/fern-api/fern/pull/3827](https://github.com/fern-api/fern/pull/3827)\
* Bump inquirer and @types/inquirer by @dependabot in [https://github.com/fern-api/fern/pull/3828](https://github.com/fern-api/fern/pull/3828)\
* Bump braces from 3.0.2 to 3.0.3 by @dependabot in [https://github.com/fern-api/fern/pull/3837](https://github.com/fern-api/fern/pull/3837)\
* Bump github.com/fern-api/generator-exec-go from 0.0.874 to 0.0.877 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3825](https://github.com/fern-api/fern/pull/3825)\
* Bump golang.org/x/mod from 0.17.0 to 0.18.0 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3824](https://github.com/fern-api/fern/pull/3824)\
* integration docs by @chdeskur in [https://github.com/fern-api/fern/pull/3795](https://github.com/fern-api/fern/pull/3795)\
* fix, python: the unchecked base model stops special casing pydantic v2 by @armandobelardo in [https://github.com/fern-api/fern/pull/3840](https://github.com/fern-api/fern/pull/3840)\
* (fix, ts): Handle undiscriminated union map key examples by @amckinney in [https://github.com/fern-api/fern/pull/3844](https://github.com/fern-api/fern/pull/3844)\
* java: upgrade to IR 46 + BigInteger support by @dcb6 in [https://github.com/fern-api/fern/pull/3814](https://github.com/fern-api/fern/pull/3814)\
* fix: image path parsing from markdown considers MDX children by @abvthecity in [https://github.com/fern-api/fern/pull/3843](https://github.com/fern-api/fern/pull/3843)\
\
## New Contributors\
\
* @ppod1991 made their first contribution in [https://github.com/fern-api/fern/pull/3833](https://github.com/fern-api/fern/pull/3833)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.30.4...0.30.5](https://github.com/fern-api/fern/compare/0.30.4...0.30.5)\
\
\
# June 11, 2024\
\
## 0.30.4\
\
**`(chore):`** ## What's Changed\
\
* fix: pagination is 1-based not 0 by @armandobelardo in [https://github.com/fern-api/fern/pull/3835](https://github.com/fern-api/fern/pull/3835)\
* (fix, openapi): fall back to default status code if none provided by @dsinghvi in [https://github.com/fern-api/fern/pull/3834](https://github.com/fern-api/fern/pull/3834)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.30.3...0.30.4](https://github.com/fern-api/fern/compare/0.30.3...0.30.4)\
\
\
# June 10, 2024\
\
## 0.30.2\
\
**`(chore):`** ## What's Changed\
\
* (fix): snippet templates for discriminated unions specify `template_inputs` by @dsinghvi in [https://github.com/fern-api/fern/pull/3808](https://github.com/fern-api/fern/pull/3808)\
* fix python seed by @dsinghvi in [https://github.com/fern-api/fern/pull/3809](https://github.com/fern-api/fern/pull/3809)\
* (feature): Write ReameConfig in IR by @amckinney in [https://github.com/fern-api/fern/pull/3786](https://github.com/fern-api/fern/pull/3786)\
* python: improve seed setup script by @dcb6 in [https://github.com/fern-api/fern/pull/3810](https://github.com/fern-api/fern/pull/3810)\
* (fix): fern definition overview repetition by @chdeskur in [https://github.com/fern-api/fern/pull/3812](https://github.com/fern-api/fern/pull/3812)\
* fix: unchecked base model respects dicts as well as objects by @armandobelardo in [https://github.com/fern-api/fern/pull/3813](https://github.com/fern-api/fern/pull/3813)\
* (feat): C# is `.NET 4` compatible by @dsinghvi in [https://github.com/fern-api/fern/pull/3816](https://github.com/fern-api/fern/pull/3816)\
* add query encoder tests for value and for None by @jmedway614 in [https://github.com/fern-api/fern/pull/3818](https://github.com/fern-api/fern/pull/3818)\
* (internal, python): python generator uses python 3.9 and pins mypy by @dsinghvi in [https://github.com/fern-api/fern/pull/3819](https://github.com/fern-api/fern/pull/3819)\
* (internal, ir-sdk): generate ir sdk with pydantic v1 by @dsinghvi in [https://github.com/fern-api/fern/pull/3820](https://github.com/fern-api/fern/pull/3820)\
* (chore, ts): Pin IRv46 TypeScript migrator versions by @amckinney in [https://github.com/fern-api/fern/pull/3821](https://github.com/fern-api/fern/pull/3821)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.30.1...0.30.2](https://github.com/fern-api/fern/compare/0.30.1...0.30.2)\
\
\
# June 7, 2024\
\
## 0.30.1\
\
**`(chore):`** ## What's Changed\
\
* fix, python: update timeout parameter docs by @armandobelardo in [https://github.com/fern-api/fern/pull/3771](https://github.com/fern-api/fern/pull/3771)\
* fix, python: mypy variance check by @armandobelardo in [https://github.com/fern-api/fern/pull/3772](https://github.com/fern-api/fern/pull/3772)\
* java: make sure oauth gated properly by @dcb6 in [https://github.com/fern-api/fern/pull/3757](https://github.com/fern-api/fern/pull/3757)\
* Bump validate-npm-package-name from 4.0.0 to 5.0.1 by @dependabot in [https://github.com/fern-api/fern/pull/3765](https://github.com/fern-api/fern/pull/3765)\
* Bump jwks-rsa from 3.0.0 to 3.1.0 by @dependabot in [https://github.com/fern-api/fern/pull/3767](https://github.com/fern-api/fern/pull/3767)\
* clean up step text by @chdeskur in [https://github.com/fern-api/fern/pull/3774](https://github.com/fern-api/fern/pull/3774)\
* Bump qs and @types/qs by @dependabot in [https://github.com/fern-api/fern/pull/3768](https://github.com/fern-api/fern/pull/3768)\
* feat: skip-slug in tabs by @abvthecity in [https://github.com/fern-api/fern/pull/3780](https://github.com/fern-api/fern/pull/3780)\
* (docs): Add Go and Ruby snippet sections by @amckinney in [https://github.com/fern-api/fern/pull/3775](https://github.com/fern-api/fern/pull/3775)\
* (feature): Add ReadmeConfig IR and generators.yml schema by @amckinney in [https://github.com/fern-api/fern/pull/3781](https://github.com/fern-api/fern/pull/3781)\
* improvement, python: unit tests are now run in CI if configured by @armandobelardo in [https://github.com/fern-api/fern/pull/3783](https://github.com/fern-api/fern/pull/3783)\
* java, improvement: error types by @dcb6 in [https://github.com/fern-api/fern/pull/3779](https://github.com/fern-api/fern/pull/3779)\
* java, feat: support response properties in sdk by @dcb6 in [https://github.com/fern-api/fern/pull/3785](https://github.com/fern-api/fern/pull/3785)\
* fix, python: the new client ensures there's a slash on the base path by @armandobelardo in [https://github.com/fern-api/fern/pull/3787](https://github.com/fern-api/fern/pull/3787)\
* (fix, python): generated python snippets respect trailing slashes by @dsinghvi in [https://github.com/fern-api/fern/pull/3789](https://github.com/fern-api/fern/pull/3789)\
* (chore, ts): Upgrade to IRv46 by @amckinney in [https://github.com/fern-api/fern/pull/3788](https://github.com/fern-api/fern/pull/3788)\
* (feat): run mypy on non integration tests by @dsinghvi in [https://github.com/fern-api/fern/pull/3794](https://github.com/fern-api/fern/pull/3794)\
* fix, python: regressions with client clean up by @armandobelardo in [https://github.com/fern-api/fern/pull/3797](https://github.com/fern-api/fern/pull/3797)\
* fix: address a number of unit test issues by @armandobelardo in [https://github.com/fern-api/fern/pull/3800](https://github.com/fern-api/fern/pull/3800)\
* java, fix: use `@java.lang.Override` in all generated code by @dcb6 in [https://github.com/fern-api/fern/pull/3799](https://github.com/fern-api/fern/pull/3799)\
* (eslint): check for `no-misused-promises` by @dsinghvi in [https://github.com/fern-api/fern/pull/3801](https://github.com/fern-api/fern/pull/3801)\
* upgrade: fdr-sdk by @abvthecity in [https://github.com/fern-api/fern/pull/3792](https://github.com/fern-api/fern/pull/3792)\
* improvement: add local configuration for python by @armandobelardo in [https://github.com/fern-api/fern/pull/3803](https://github.com/fern-api/fern/pull/3803)\
* (fix): Publish ir-types-latest by @amckinney in [https://github.com/fern-api/fern/pull/3806](https://github.com/fern-api/fern/pull/3806)\
* Add Extra Field Support for FastAPI by @jmedway614 in [https://github.com/fern-api/fern/pull/3804](https://github.com/fern-api/fern/pull/3804)\
* java, fix: initialize `RequestOptions` `timeout` field correctly to `Optional.empty()` by @dcb6 in [https://github.com/fern-api/fern/pull/3807](https://github.com/fern-api/fern/pull/3807)\
* (fix, typescript): prefer `TextDecoder` when deserializing stream data by @dsinghvi in [https://github.com/fern-api/fern/pull/3791](https://github.com/fern-api/fern/pull/3791)\
\
## New Contributors\
\
* @jmedway614 made their first contribution in [https://github.com/fern-api/fern/pull/3804](https://github.com/fern-api/fern/pull/3804)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.30.0...0.30.1](https://github.com/fern-api/fern/compare/0.30.0...0.30.1)\
\
\
# June 6, 2024\
\
## 0.30.1-rc1\
\
**`(chore):`** ## What's Changed\
\
* fix, python: update timeout parameter docs by @armandobelardo in [https://github.com/fern-api/fern/pull/3771](https://github.com/fern-api/fern/pull/3771)\
* fix, python: mypy variance check by @armandobelardo in [https://github.com/fern-api/fern/pull/3772](https://github.com/fern-api/fern/pull/3772)\
* java: make sure oauth gated properly by @dcb6 in [https://github.com/fern-api/fern/pull/3757](https://github.com/fern-api/fern/pull/3757)\
* Bump validate-npm-package-name from 4.0.0 to 5.0.1 by @dependabot in [https://github.com/fern-api/fern/pull/3765](https://github.com/fern-api/fern/pull/3765)\
* Bump jwks-rsa from 3.0.0 to 3.1.0 by @dependabot in [https://github.com/fern-api/fern/pull/3767](https://github.com/fern-api/fern/pull/3767)\
* clean up step text by @chdeskur in [https://github.com/fern-api/fern/pull/3774](https://github.com/fern-api/fern/pull/3774)\
* Bump qs and @types/qs by @dependabot in [https://github.com/fern-api/fern/pull/3768](https://github.com/fern-api/fern/pull/3768)\
* feat: skip-slug in tabs by @abvthecity in [https://github.com/fern-api/fern/pull/3780](https://github.com/fern-api/fern/pull/3780)\
* (docs): Add Go and Ruby snippet sections by @amckinney in [https://github.com/fern-api/fern/pull/3775](https://github.com/fern-api/fern/pull/3775)\
* (feature): Add ReadmeConfig IR and generators.yml schema by @amckinney in [https://github.com/fern-api/fern/pull/3781](https://github.com/fern-api/fern/pull/3781)\
* improvement, python: unit tests are now run in CI if configured by @armandobelardo in [https://github.com/fern-api/fern/pull/3783](https://github.com/fern-api/fern/pull/3783)\
* java, improvement: error types by @dcb6 in [https://github.com/fern-api/fern/pull/3779](https://github.com/fern-api/fern/pull/3779)\
* java, feat: support response properties in sdk by @dcb6 in [https://github.com/fern-api/fern/pull/3785](https://github.com/fern-api/fern/pull/3785)\
* fix, python: the new client ensures there's a slash on the base path by @armandobelardo in [https://github.com/fern-api/fern/pull/3787](https://github.com/fern-api/fern/pull/3787)\
* (fix, python): generated python snippets respect trailing slashes by @dsinghvi in [https://github.com/fern-api/fern/pull/3789](https://github.com/fern-api/fern/pull/3789)\
* (chore, ts): Upgrade to IRv46 by @amckinney in [https://github.com/fern-api/fern/pull/3788](https://github.com/fern-api/fern/pull/3788)\
* (feat): run mypy on non integration tests by @dsinghvi in [https://github.com/fern-api/fern/pull/3794](https://github.com/fern-api/fern/pull/3794)\
* fix, python: regressions with client clean up by @armandobelardo in [https://github.com/fern-api/fern/pull/3797](https://github.com/fern-api/fern/pull/3797)\
* fix: address a number of unit test issues by @armandobelardo in [https://github.com/fern-api/fern/pull/3800](https://github.com/fern-api/fern/pull/3800)\
* java, fix: use `@java.lang.Override` in all generated code by @dcb6 in [https://github.com/fern-api/fern/pull/3799](https://github.com/fern-api/fern/pull/3799)\
* (eslint): check for `no-misused-promises` by @dsinghvi in [https://github.com/fern-api/fern/pull/3801](https://github.com/fern-api/fern/pull/3801)\
* upgrade: fdr-sdk by @abvthecity in [https://github.com/fern-api/fern/pull/3792](https://github.com/fern-api/fern/pull/3792)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.30.0...0.30.1-rc1](https://github.com/fern-api/fern/compare/0.30.0...0.30.1-rc1)\
\
\
# June 3, 2024\
\
## 0.30.0-rc0\
\
**`(chore):`** ## What's Changed\
\
* fix: address a number of papercuts in the mock server and python unit tests by @armandobelardo in [https://github.com/fern-api/fern/pull/3749](https://github.com/fern-api/fern/pull/3749)\
* (fix, ts): Simplify OAuth error handling by @amckinney in [https://github.com/fern-api/fern/pull/3752](https://github.com/fern-api/fern/pull/3752)\
* docs: add java examples by @dcb6 in [https://github.com/fern-api/fern/pull/3755](https://github.com/fern-api/fern/pull/3755)\
* (feat, python): write out example ids in generated snippets by @dsinghvi in [https://github.com/fern-api/fern/pull/3750](https://github.com/fern-api/fern/pull/3750)\
* docs: remove maxHeight prop by @chdeskur in [https://github.com/fern-api/fern/pull/3734](https://github.com/fern-api/fern/pull/3734)\
* (fix, typescript): peer dependencies are always persisted by @dsinghvi in [https://github.com/fern-api/fern/pull/3758](https://github.com/fern-api/fern/pull/3758)\
* docs: added custom css & js page by @atwooddc in [https://github.com/fern-api/fern/pull/3753](https://github.com/fern-api/fern/pull/3753)\
* (fix, typescript): example identifiers are added to generated snippets by @dsinghvi in [https://github.com/fern-api/fern/pull/3759](https://github.com/fern-api/fern/pull/3759)\
* improvement, python: clean up endpoint functions by centralizing logic by @armandobelardo in [https://github.com/fern-api/fern/pull/3761](https://github.com/fern-api/fern/pull/3761)\
* improvement: add literal example type and add id to example by @armandobelardo in [https://github.com/fern-api/fern/pull/3756](https://github.com/fern-api/fern/pull/3756)\
* improvement: filter out nulls after merging API specs by @armandobelardo in [https://github.com/fern-api/fern/pull/3710](https://github.com/fern-api/fern/pull/3710)\
* (docs): Add discriminated union section by @amckinney in [https://github.com/fern-api/fern/pull/3763](https://github.com/fern-api/fern/pull/3763)\
* improvement: add a flag to allow python to generate discriminated unions as undiscriminated unions by @armandobelardo in [https://github.com/fern-api/fern/pull/3740](https://github.com/fern-api/fern/pull/3740)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.29.5...0.30.0-rc0](https://github.com/fern-api/fern/compare/0.29.5...0.30.0-rc0)\
\
\
# May 31, 2024\
\
## 0.29.4\
\
**`(chore):`** ## What's Changed\
\
* (fix, typescript): disable integration test generation by @dsinghvi in [https://github.com/fern-api/fern/pull/3731](https://github.com/fern-api/fern/pull/3731)\
* (fix, typescript): generated GitHub workflows do not assume `fern` present by @dsinghvi in [https://github.com/fern-api/fern/pull/3732](https://github.com/fern-api/fern/pull/3732)\
* fix, python: add type annotations to test vars by @armandobelardo in [https://github.com/fern-api/fern/pull/3733](https://github.com/fern-api/fern/pull/3733)\
* (feature, typescript): support `extraPeerDependencies` and `extraPeerDependenciesMeta` in custom config by @dsinghvi in [https://github.com/fern-api/fern/pull/3739](https://github.com/fern-api/fern/pull/3739)\
* docs: add note on GFM support by @chdeskur in [https://github.com/fern-api/fern/pull/3738](https://github.com/fern-api/fern/pull/3738)\
* Bump eslint-plugin-jest from 27.0.4 to 27.9.0 by @dependabot in [https://github.com/fern-api/fern/pull/3539](https://github.com/fern-api/fern/pull/3539)\
* Bump golang.org/x/tools from 0.20.0 to 0.21.0 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3538](https://github.com/fern-api/fern/pull/3538)\
* (feat, python): support optional python deps + extras by @dsinghvi in [https://github.com/fern-api/fern/pull/3742](https://github.com/fern-api/fern/pull/3742)\
* java, improvement: run seed faster using local mode by @dcb6 in [https://github.com/fern-api/fern/pull/3741](https://github.com/fern-api/fern/pull/3741)\
* java, fix: generate builders even when types have no fields by @dcb6 in [https://github.com/fern-api/fern/pull/3744](https://github.com/fern-api/fern/pull/3744)\
* (fix, csharp): support `List<OneOf>` deserialization by @dsinghvi in [https://github.com/fern-api/fern/pull/3745](https://github.com/fern-api/fern/pull/3745)\
* (feat, openapi): add support for `x-fern-idempotency-headers` by @dsinghvi in [https://github.com/fern-api/fern/pull/3746](https://github.com/fern-api/fern/pull/3746)\
\
## New Contributors\
\
* @chdeskur made their first contribution in [https://github.com/fern-api/fern/pull/3738](https://github.com/fern-api/fern/pull/3738)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.29.3...0.29.4](https://github.com/fern-api/fern/compare/0.29.3...0.29.4)\
\
\
# May 30, 2024\
\
## 0.29.3\
\
**`(chore):`** ## What's Changed\
\
* (fix): write mock definition by @dsinghvi in [https://github.com/fern-api/fern/pull/3730](https://github.com/fern-api/fern/pull/3730)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.29.2...0.29.3](https://github.com/fern-api/fern/compare/0.29.2...0.29.3)\
\
\
# May 29, 2024\
\
## 0.29.2\
\
**`(chore):`** ## What's Changed\
\
* docs: fix broken links and anchor text by @atwooddc in [https://github.com/fern-api/fern/pull/3718](https://github.com/fern-api/fern/pull/3718)\
* docs: nested tabs auto pagination page bug by @atwooddc in [https://github.com/fern-api/fern/pull/3717](https://github.com/fern-api/fern/pull/3717)\
* (fix, internal): do deploys of fern docs to dev by @dsinghvi in [https://github.com/fern-api/fern/pull/3529](https://github.com/fern-api/fern/pull/3529)\
* fix, python: flatten optional pagination return types by @armandobelardo in [https://github.com/fern-api/fern/pull/3721](https://github.com/fern-api/fern/pull/3721)\
* java, fix: de-conflict undiscriminated unions by @dcb6 in [https://github.com/fern-api/fern/pull/3719](https://github.com/fern-api/fern/pull/3719)\
* improvement, python: literal fields are now defaulted by @armandobelardo in [https://github.com/fern-api/fern/pull/3724](https://github.com/fern-api/fern/pull/3724)\
* (fix, csharp): enum deserialization by @armandobelardo in [https://github.com/fern-api/fern/pull/3725](https://github.com/fern-api/fern/pull/3725)\
* docs: added subtitle documentation on frontmatter page by @atwooddc in [https://github.com/fern-api/fern/pull/3723](https://github.com/fern-api/fern/pull/3723)\
* docs: added api reference summary by @atwooddc in [https://github.com/fern-api/fern/pull/3716](https://github.com/fern-api/fern/pull/3716)\
* docs: fixed broken links and updated openapi generator info by @atwooddc in [https://github.com/fern-api/fern/pull/3700](https://github.com/fern-api/fern/pull/3700)\
* (fix, seed): Fix snapshots by @dcb6 in [https://github.com/fern-api/fern/pull/3726](https://github.com/fern-api/fern/pull/3726)\
* (fix, csharp): streamline enum + union serde by @dsinghvi in [https://github.com/fern-api/fern/pull/3727](https://github.com/fern-api/fern/pull/3727)\
* (fix, typescript): remove `node:stream` import to play nicely with webpack by @dsinghvi in [https://github.com/fern-api/fern/pull/3728](https://github.com/fern-api/fern/pull/3728)\
* (fix, ts): Support OAuth for SDKs that set neverThrowErrors by @amckinney in [https://github.com/fern-api/fern/pull/3729](https://github.com/fern-api/fern/pull/3729)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.29.1...0.29.2](https://github.com/fern-api/fern/compare/0.29.1...0.29.2)\
\
\
# May 28, 2024\
\
## 0.29.1\
\
**`(chore):`** ## What's Changed\
\
* fix, python: do not manually specify custom license file by @armandobelardo in [https://github.com/fern-api/fern/pull/3697](https://github.com/fern-api/fern/pull/3697)\
* build(deps): bump github.com/fern-api/generator-exec-go from 0.0.817 to 0.0.823 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3653](https://github.com/fern-api/fern/pull/3653)\
* fix, fastapi: fixes path prefixes and construction by @armandobelardo in [https://github.com/fern-api/fern/pull/3699](https://github.com/fern-api/fern/pull/3699)\
* (docs) Add Building Your Docs section by @dannysheridan in [https://github.com/fern-api/fern/pull/3698](https://github.com/fern-api/fern/pull/3698)\
* docs: individualized title tags by @atwooddc in [https://github.com/fern-api/fern/pull/3704](https://github.com/fern-api/fern/pull/3704)\
* docs: add img alt attributes by @atwooddc in [https://github.com/fern-api/fern/pull/3703](https://github.com/fern-api/fern/pull/3703)\
* docs fixed tabs meta description typo by @atwooddc in [https://github.com/fern-api/fern/pull/3702](https://github.com/fern-api/fern/pull/3702)\
* (docs) Add custom subdomain and subpath instructions by @dannysheridan in [https://github.com/fern-api/fern/pull/3705](https://github.com/fern-api/fern/pull/3705)\
* (fix, docs): add missing dashes for \'93--instance\'94 in CLI docs by @zachkirsch in [https://github.com/fern-api/fern/pull/3709](https://github.com/fern-api/fern/pull/3709)\
* build(deps): bump github.com/fern-api/generator-exec-go from 0.0.823 to 0.0.874 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3707](https://github.com/fern-api/fern/pull/3707)\
* fix: ruby snippets now respect the full module path of the function call by @armandobelardo in [https://github.com/fern-api/fern/pull/3706](https://github.com/fern-api/fern/pull/3706)\
* (fix, csharp): make C# sdk .NET 6 compatible by @dsinghvi in [https://github.com/fern-api/fern/pull/3711](https://github.com/fern-api/fern/pull/3711)\
* (fix, csharp): generated GitHub workflows use `.NET` 8.x by @dsinghvi in [https://github.com/fern-api/fern/pull/3712](https://github.com/fern-api/fern/pull/3712)\
* fix: fastapi now has all pydantic utilities it needs by @armandobelardo in [https://github.com/fern-api/fern/pull/3713](https://github.com/fern-api/fern/pull/3713)\
* fix, python: add typing lib for dateutils by @armandobelardo in [https://github.com/fern-api/fern/pull/3714](https://github.com/fern-api/fern/pull/3714)\
* Docs remove redirect links by @atwooddc in [https://github.com/fern-api/fern/pull/3701](https://github.com/fern-api/fern/pull/3701)\
* (fix): `x-fern-base-path` impacts endpoint paths instead of `api.yml` base path by @dsinghvi in [https://github.com/fern-api/fern/pull/3720](https://github.com/fern-api/fern/pull/3720)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.29.1-rc0...0.29.2](https://github.com/fern-api/fern/compare/0.29.1-rc0...0.29.2)\
\
\
# May 24, 2024\
\
## 0.29.1-rc0\
\
**`(chore):`** ## What's Changed\
\
* (feat, csharp): generate `Environments.cs` and populate default `BaseURL` by @dsinghvi in [https://github.com/fern-api/fern/pull/3677](https://github.com/fern-api/fern/pull/3677)\
* (fix, csharp): package in LICENSE in `.csproj` by @dsinghvi in [https://github.com/fern-api/fern/pull/3678](https://github.com/fern-api/fern/pull/3678)\
* (fix, python): re-add python unit tests by @armandobelardo in [https://github.com/fern-api/fern/pull/3609](https://github.com/fern-api/fern/pull/3609)\
* (chore, python): fix typo in generated comments by @armandobelardo in [https://github.com/fern-api/fern/pull/3680](https://github.com/fern-api/fern/pull/3680)\
* fix, python: do not run `fern test` in CI yet by @armandobelardo in [https://github.com/fern-api/fern/pull/3683](https://github.com/fern-api/fern/pull/3683)\
* docs changed trivial anchor text by @atwooddc in [https://github.com/fern-api/fern/pull/3687](https://github.com/fern-api/fern/pull/3687)\
* docs: unbolded sections for seo by @atwooddc in [https://github.com/fern-api/fern/pull/3686](https://github.com/fern-api/fern/pull/3686)\
* docs: api definition docs and mdx descriptions for seo by @atwooddc in [https://github.com/fern-api/fern/pull/3685](https://github.com/fern-api/fern/pull/3685)\
* (fix, csharp): scan `EnumMember` annotations when serializaing to string by @dsinghvi in [https://github.com/fern-api/fern/pull/3688](https://github.com/fern-api/fern/pull/3688)\
* fix, python: request bodies respect literals again by @armandobelardo in [https://github.com/fern-api/fern/pull/3689](https://github.com/fern-api/fern/pull/3689)\
* (fix, python): support  endpoint method names by @dsinghvi in [https://github.com/fern-api/fern/pull/3690](https://github.com/fern-api/fern/pull/3690)\
* (fix, csharp): inlined requests that are 1:1 with HTTP bodies now have JSON annotations by @dsinghvi in [https://github.com/fern-api/fern/pull/3691](https://github.com/fern-api/fern/pull/3691)\
* docs cli UI changed to Accordion Group by @atwooddc in [https://github.com/fern-api/fern/pull/3681](https://github.com/fern-api/fern/pull/3681)\
* docs: fixing broken links by @atwooddc in [https://github.com/fern-api/fern/pull/3667](https://github.com/fern-api/fern/pull/3667)\
* Update extensions.mdx by @dannysheridan in [https://github.com/fern-api/fern/pull/3658](https://github.com/fern-api/fern/pull/3658)\
* feat: markdown-in-markdown - load markdown from another markdown file. by @abvthecity in [https://github.com/fern-api/fern/pull/3693](https://github.com/fern-api/fern/pull/3693)\
* java: oauth improvements including token refresh by @dcb6 in [https://github.com/fern-api/fern/pull/3682](https://github.com/fern-api/fern/pull/3682)\
* (feat, typescript): accept abort signals as request options by @dsinghvi in [https://github.com/fern-api/fern/pull/3694](https://github.com/fern-api/fern/pull/3694)\
* (fix, typescript): pass abort signal to SSE/JSON streams by @dsinghvi in [https://github.com/fern-api/fern/pull/3695](https://github.com/fern-api/fern/pull/3695)\
* (feat, express): pass `next` into express handlers by @dsinghvi in [https://github.com/fern-api/fern/pull/3696](https://github.com/fern-api/fern/pull/3696)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.29.0...0.29.1-rc0](https://github.com/fern-api/fern/compare/0.29.0...0.29.1-rc0)\
\
\
# May 22, 2024\
\
## 0.29.0\
\
**`(chore):`** ## What's Changed\
\
* (fix, python): fix naming conflicts with inlined body parameters by @armandobelardo in [https://github.com/fern-api/fern/pull/3673](https://github.com/fern-api/fern/pull/3673)\
* (fix, python): correct snippets for optional referenced requests when\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3676](https://github.com/fern-api/fern/pull/3676)\
* fix, java: make java compatible with java 8 by @dcb6 in [https://github.com/fern-api/fern/pull/3671](https://github.com/fern-api/fern/pull/3671)\
* (fix, python): use safe names wherever there's no string concat by @armandobelardo in [https://github.com/fern-api/fern/pull/3674](https://github.com/fern-api/fern/pull/3674)\
* (feature, openapi): Map additionalProperties to extra-properties by @amckinney in [https://github.com/fern-api/fern/pull/3675](https://github.com/fern-api/fern/pull/3675)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.28.0...0.29.0](https://github.com/fern-api/fern/compare/0.28.0...0.29.0)\
\
\
# May 21, 2024\
\
## 0.27.1-rc0\
\
**`(chore):`** ## What's Changed\
\
* (feature): Add support for default values and validation rules by @amckinney in [https://github.com/fern-api/fern/pull/3640](https://github.com/fern-api/fern/pull/3640)\
* improvement: add in config to enrich pypi metadata by @armandobelardo in [https://github.com/fern-api/fern/pull/3660](https://github.com/fern-api/fern/pull/3660)\
* (fix, chsarp): `.csproj` generation includes license, version, and github url by @dsinghvi in [https://github.com/fern-api/fern/pull/3659](https://github.com/fern-api/fern/pull/3659)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.27.0...0.27.1-rc0](https://github.com/fern-api/fern/compare/0.27.0...0.27.1-rc0)\
\
\
# May 20, 2024\
\
## 0.26.11\
\
**`(chore):`** ## What's Changed\
\
* (feat, docs): document local previews by @dsinghvi in [https://github.com/fern-api/fern/pull/3649](https://github.com/fern-api/fern/pull/3649)\
* chore: add identifier override to further specify snippets by @armandobelardo in [https://github.com/fern-api/fern/pull/3642](https://github.com/fern-api/fern/pull/3642)\
* fixed broken internal links on docs site by @atwooddc in [https://github.com/fern-api/fern/pull/3656](https://github.com/fern-api/fern/pull/3656)\
* chore: add v1 websocket events in local docs preview by @abvthecity in [https://github.com/fern-api/fern/pull/3655](https://github.com/fern-api/fern/pull/3655)\
* fix, python: deconflict parameter names when inlining request parameters by @armandobelardo in [https://github.com/fern-api/fern/pull/3650](https://github.com/fern-api/fern/pull/3650)\
* (fix): support running docs dev server on a port by @dsinghvi in [https://github.com/fern-api/fern/pull/3657](https://github.com/fern-api/fern/pull/3657)\
\
## New Contributors\
\
* @atwooddc made their first contribution in [https://github.com/fern-api/fern/pull/3656](https://github.com/fern-api/fern/pull/3656)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.26.10...0.26.11](https://github.com/fern-api/fern/compare/0.26.10...0.26.11)\
\
\
# May 19, 2024\
\
## 0.26.10-rc1\
\
**`(chore):`** ## What's Changed\
\
* chore: document auto-pagination configuration by @armandobelardo in [https://github.com/fern-api/fern/pull/3644](https://github.com/fern-api/fern/pull/3644)\
* Tidy up python generator docs by @fabubaker in [https://github.com/fern-api/fern/pull/3645](https://github.com/fern-api/fern/pull/3645)\
* (feat, local preview): setup dynamic local preview by @dsinghvi in [https://github.com/fern-api/fern/pull/3634](https://github.com/fern-api/fern/pull/3634)\
* refactor: share common logic between publishDocs and previewDocs by @abvthecity in [https://github.com/fern-api/fern/pull/3639](https://github.com/fern-api/fern/pull/3639)\
\
## New Contributors\
\
* @fabubaker made their first contribution in [https://github.com/fern-api/fern/pull/3645](https://github.com/fern-api/fern/pull/3645)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.26.10-rc0...0.26.10-rc1](https://github.com/fern-api/fern/compare/0.26.10-rc0...0.26.10-rc1)\
\
\
# May 17, 2024\
\
## 0.26.10-rc0\
\
**`(chore):`** ## What's Changed\
\
* chore: clean up some nuget references by @armandobelardo in [https://github.com/fern-api/fern/pull/3627](https://github.com/fern-api/fern/pull/3627)\
* (fix, ts): OAuth provides an optional token by @amckinney in [https://github.com/fern-api/fern/pull/3633](https://github.com/fern-api/fern/pull/3633)\
* improvement, java: stop generating extra semicolon by @dcb6 in [https://github.com/fern-api/fern/pull/3631](https://github.com/fern-api/fern/pull/3631)\
* chore, python: improve snippets for streaming by @armandobelardo in [https://github.com/fern-api/fern/pull/3630](https://github.com/fern-api/fern/pull/3630)\
* improvement: python now respects deep object query parameters by @armandobelardo in [https://github.com/fern-api/fern/pull/3629](https://github.com/fern-api/fern/pull/3629)\
* fix: fern cli now appropriately awaits docker pull by @armandobelardo in [https://github.com/fern-api/fern/pull/3636](https://github.com/fern-api/fern/pull/3636)\
* (docs, improvement): add guide on how to publish public sdks by @dsinghvi in [https://github.com/fern-api/fern/pull/3638](https://github.com/fern-api/fern/pull/3638)\
* (feat): Add default values, validation rules, and big integer to primitives by @dsinghvi in [https://github.com/fern-api/fern/pull/3625](https://github.com/fern-api/fern/pull/3625)\
* feat: add seo and metadata configuration in docs.yml by @abvthecity in [https://github.com/fern-api/fern/pull/3635](https://github.com/fern-api/fern/pull/3635)\
* Update welcome.mdx by @dannysheridan in [https://github.com/fern-api/fern/pull/3637](https://github.com/fern-api/fern/pull/3637)\
* fix formatting of our own java code by @dcb6 in [https://github.com/fern-api/fern/pull/3641](https://github.com/fern-api/fern/pull/3641)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.26.9...0.26.10-rc0](https://github.com/fern-api/fern/compare/0.26.9...0.26.10-rc0)\
\
\
# May 15, 2024\
\
## 0.26.9-rc0\
\
**`(chore):`** ## What's Changed\
\
* (fix, ts): Client credentials are optional with env vars by @amckinney in [https://github.com/fern-api/fern/pull/3617](https://github.com/fern-api/fern/pull/3617)\
* fix: upload images in changelogs by @abvthecity in [https://github.com/fern-api/fern/pull/3623](https://github.com/fern-api/fern/pull/3623)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.26.8...0.26.9](https://github.com/fern-api/fern/compare/0.26.8...0.26.9)\
\
\
# May 14, 2024\
\
## 0.26.6\
\
**`(chore):`** ## What's Changed\
\
* (fix, openapi): Consolidate enums into discriminants by @amckinney in [https://github.com/fern-api/fern/pull/3607](https://github.com/fern-api/fern/pull/3607)\
* (feature, ts): Support oauth client credentials flow by @amckinney in [https://github.com/fern-api/fern/pull/3578](https://github.com/fern-api/fern/pull/3578)\
* (fix, openapi): OpenAPI importer now parses list examples that are specific to a field by @dsinghvi in [https://github.com/fern-api/fern/pull/3613](https://github.com/fern-api/fern/pull/3613)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.26.5...0.26.6](https://github.com/fern-api/fern/compare/0.26.5...0.26.6)\
\
\
# May 13, 2024\
\
## 0.26.4\
\
**`(chore):`** ## What's Changed\
\
* (docs) Add intro section by @dannysheridan in [https://github.com/fern-api/fern/pull/3547](https://github.com/fern-api/fern/pull/3547)\
* (chore, fastapi, ruby sdk) release versions by @dannysheridan in [https://github.com/fern-api/fern/pull/3587](https://github.com/fern-api/fern/pull/3587)\
* (chore, pydantic): Release 0.9.0 by @dannysheridan in [https://github.com/fern-api/fern/pull/3586](https://github.com/fern-api/fern/pull/3586)\
* (document) reusable code snippets by @dannysheridan in [https://github.com/fern-api/fern/pull/3524](https://github.com/fern-api/fern/pull/3524)\
* remove page that does not exist from docs by @armandobelardo in [https://github.com/fern-api/fern/pull/3589](https://github.com/fern-api/fern/pull/3589)\
* improvement: add  `extra_dev_dependencies` to python generator by @armandobelardo in [https://github.com/fern-api/fern/pull/3585](https://github.com/fern-api/fern/pull/3585)\
* feat: support Stream and SSE in ExampleResponseSchema by @abvthecity in [https://github.com/fern-api/fern/pull/3577](https://github.com/fern-api/fern/pull/3577)\
* improvement: also run fetch latest version on `fern init` by @armandobelardo in [https://github.com/fern-api/fern/pull/3588](https://github.com/fern-api/fern/pull/3588)\
* improvement: allow a break the glass override of the min-python version by @armandobelardo in [https://github.com/fern-api/fern/pull/3591](https://github.com/fern-api/fern/pull/3591)\
* feat: allow overriding api reference slug in docs by @abvthecity in [https://github.com/fern-api/fern/pull/3575](https://github.com/fern-api/fern/pull/3575)\
* break: release python 2.x by @armandobelardo in [https://github.com/fern-api/fern/pull/3590](https://github.com/fern-api/fern/pull/3590)\
* fix: treat multipart form as form by @abvthecity in [https://github.com/fern-api/fern/pull/3553](https://github.com/fern-api/fern/pull/3553)\
* (feat, csharp): several fixes including arbitrary nested subpackage clients by @dsinghvi in [https://github.com/fern-api/fern/pull/3593](https://github.com/fern-api/fern/pull/3593)\
* (fix, csharp): support sending inlined requests that are entirely bodies by @dsinghvi in [https://github.com/fern-api/fern/pull/3594](https://github.com/fern-api/fern/pull/3594)\
* chore: document naming and env overrides for basic and bearer auth in\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3596](https://github.com/fern-api/fern/pull/3596)\
* feat: streaming and sse examples by @abvthecity in [https://github.com/fern-api/fern/pull/3592](https://github.com/fern-api/fern/pull/3592)\
* fix issue#3566 by @last-developer in [https://github.com/fern-api/fern/pull/3597](https://github.com/fern-api/fern/pull/3597)\
* (fix, docs) webhook indentation by @dannysheridan in [https://github.com/fern-api/fern/pull/3600](https://github.com/fern-api/fern/pull/3600)\
* (fix):`ir.json` are not out of date for seed by @dsinghvi in [https://github.com/fern-api/fern/pull/3598](https://github.com/fern-api/fern/pull/3598)\
* (fix): `fern add` with a new `--group` works by @dsinghvi in [https://github.com/fern-api/fern/pull/3602](https://github.com/fern-api/fern/pull/3602)\
\
## New Contributors\
\
* @last-developer made their first contribution in [https://github.com/fern-api/fern/pull/3597](https://github.com/fern-api/fern/pull/3597)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.26.3...0.26.4](https://github.com/fern-api/fern/compare/0.26.3...0.26.4)\
\
\
# May 9, 2024\
\
## 0.26.0\
\
**`(chore):`** ## What's Changed\
\
* (feat, definition): support response status codes by @dsinghvi in [https://github.com/fern-api/fern/pull/3580](https://github.com/fern-api/fern/pull/3580)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.25.0...0.26.0](https://github.com/fern-api/fern/compare/0.25.0...0.26.0)\
\
\
# May 8, 2024\
\
## 0.25.0\
\
**`(chore):`** ## What's Changed\
\
* feat: add origin and ability to update API spec via CLI by @armandobelardo in [https://github.com/fern-api/fern/pull/3533](https://github.com/fern-api/fern/pull/3533)\
* internal: add in tags and labels for docker images for use in upgrade\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3542](https://github.com/fern-api/fern/pull/3542)\
* Bump @fern-api/fdr-sdk from 0.82.1-32d571a0d to 0.82.1-6020e1266 by @dependabot in [https://github.com/fern-api/fern/pull/3540](https://github.com/fern-api/fern/pull/3540)\
* (improvement, express): Remove unnecessary console.error by @amckinney in [https://github.com/fern-api/fern/pull/3541](https://github.com/fern-api/fern/pull/3541)\
* fix: update docker cli usage for ts sdks by @armandobelardo in [https://github.com/fern-api/fern/pull/3544](https://github.com/fern-api/fern/pull/3544)\
* (feat, cli): introduce error examples in the fern definition by @dsinghvi in [https://github.com/fern-api/fern/pull/3546](https://github.com/fern-api/fern/pull/3546)\
* (feat, ir): add example errors to ir and fdr by @dsinghvi in [https://github.com/fern-api/fern/pull/3548](https://github.com/fern-api/fern/pull/3548)\
* (feature, ts): Support upload endpoints with file arrays by @amckinney in [https://github.com/fern-api/fern/pull/3543](https://github.com/fern-api/fern/pull/3543)\
* (fix): ete tests are green by @dsinghvi in [https://github.com/fern-api/fern/pull/3550](https://github.com/fern-api/fern/pull/3550)\
* (fix): openapi ir to fern carries through error examples by @dsinghvi in [https://github.com/fern-api/fern/pull/3551](https://github.com/fern-api/fern/pull/3551)\
* (fix): pass in example.value to error converter by @dsinghvi in [https://github.com/fern-api/fern/pull/3554](https://github.com/fern-api/fern/pull/3554)\
* (fix, openapi): Recursively visit nested anyOf schemas by @amckinney in [https://github.com/fern-api/fern/pull/3536](https://github.com/fern-api/fern/pull/3536)\
* (express): Release 0.12.0-rc2 by @amckinney in [https://github.com/fern-api/fern/pull/3555](https://github.com/fern-api/fern/pull/3555)\
* fix, java: do not require non-auth headers if auth is mandatory by @armandobelardo in [https://github.com/fern-api/fern/pull/3549](https://github.com/fern-api/fern/pull/3549)\
* (fix): add `node-gyp` to make yarn installs faster by @dsinghvi in [https://github.com/fern-api/fern/pull/3552](https://github.com/fern-api/fern/pull/3552)\
* Revert "(fix): add `node-gyp` to make yarn installs faster" by @dsinghvi in [https://github.com/fern-api/fern/pull/3558](https://github.com/fern-api/fern/pull/3558)\
* (fix): OpenAPI converter only adds unique error examples by @dsinghvi in [https://github.com/fern-api/fern/pull/3556](https://github.com/fern-api/fern/pull/3556)\
* (fix, go): Disable url tags for in-lined body properties by @amckinney in [https://github.com/fern-api/fern/pull/3557](https://github.com/fern-api/fern/pull/3557)\
* (feat, express): add `skipRequestValidation` configuration to the express generator by @dsinghvi in [https://github.com/fern-api/fern/pull/3560](https://github.com/fern-api/fern/pull/3560)\
* (fix) \\[wip] java empty response body instead of null by @dcb6 in [https://github.com/fern-api/fern/pull/3545](https://github.com/fern-api/fern/pull/3545)\
* Document new `background` prop for `Frame` component by @KenzoBenzo in [https://github.com/fern-api/fern/pull/3559](https://github.com/fern-api/fern/pull/3559)\
* (improvment, ir): Improve OAuth IR customizability by @amckinney in [https://github.com/fern-api/fern/pull/3563](https://github.com/fern-api/fern/pull/3563)\
* (docs) consolidate code snippets and code block markdown pages by @abvthecity in [https://github.com/fern-api/fern/pull/3562](https://github.com/fern-api/fern/pull/3562)\
* fix: deduplicate image filepaths to upload by @abvthecity in [https://github.com/fern-api/fern/pull/3564](https://github.com/fern-api/fern/pull/3564)\
* (fix, internal): seed exits when docker fails to build by @dsinghvi in [https://github.com/fern-api/fern/pull/3568](https://github.com/fern-api/fern/pull/3568)\
* (internal, fix): rewrite inputs and run seed on ir changes by @dsinghvi in [https://github.com/fern-api/fern/pull/3569](https://github.com/fern-api/fern/pull/3569)\
* fix: do not add header to java map unless not null by @armandobelardo in [https://github.com/fern-api/fern/pull/3567](https://github.com/fern-api/fern/pull/3567)\
* (fix, docs): improve docs on augmenting generators with customization by @dsinghvi in [https://github.com/fern-api/fern/pull/3570](https://github.com/fern-api/fern/pull/3570)\
* docs: sidebar icons by @abvthecity in [https://github.com/fern-api/fern/pull/3574](https://github.com/fern-api/fern/pull/3574)\
* fix: perform the correct null check on headers by @armandobelardo in [https://github.com/fern-api/fern/pull/3571](https://github.com/fern-api/fern/pull/3571)\
* fix, ir: fall back to the generated name when creating schemas if the\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3572](https://github.com/fern-api/fern/pull/3572)\
\
## New Contributors\
\
* @dcb6 made their first contribution in [https://github.com/fern-api/fern/pull/3545](https://github.com/fern-api/fern/pull/3545)\
* @KenzoBenzo made their first contribution in [https://github.com/fern-api/fern/pull/3559](https://github.com/fern-api/fern/pull/3559)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.24.0...0.25.0](https://github.com/fern-api/fern/compare/0.24.0...0.25.0)\
\
\
# May 7, 2024\
\
## 0.25.0-rc0\
\
**`(chore):`** ## What's Changed\
\
* feat: add origin and ability to update API spec via CLI by @armandobelardo in [https://github.com/fern-api/fern/pull/3533](https://github.com/fern-api/fern/pull/3533)\
* internal: add in tags and labels for docker images for use in upgrade\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3542](https://github.com/fern-api/fern/pull/3542)\
* Bump @fern-api/fdr-sdk from 0.82.1-32d571a0d to 0.82.1-6020e1266 by @dependabot in [https://github.com/fern-api/fern/pull/3540](https://github.com/fern-api/fern/pull/3540)\
* (improvement, express): Remove unnecessary console.error by @amckinney in [https://github.com/fern-api/fern/pull/3541](https://github.com/fern-api/fern/pull/3541)\
* fix: update docker cli usage for ts sdks by @armandobelardo in [https://github.com/fern-api/fern/pull/3544](https://github.com/fern-api/fern/pull/3544)\
* (feat, cli): introduce error examples in the fern definition by @dsinghvi in [https://github.com/fern-api/fern/pull/3546](https://github.com/fern-api/fern/pull/3546)\
* (feat, ir): add example errors to ir and fdr by @dsinghvi in [https://github.com/fern-api/fern/pull/3548](https://github.com/fern-api/fern/pull/3548)\
* (feature, ts): Support upload endpoints with file arrays by @amckinney in [https://github.com/fern-api/fern/pull/3543](https://github.com/fern-api/fern/pull/3543)\
* (fix): ete tests are green by @dsinghvi in [https://github.com/fern-api/fern/pull/3550](https://github.com/fern-api/fern/pull/3550)\
* (fix): openapi ir to fern carries through error examples by @dsinghvi in [https://github.com/fern-api/fern/pull/3551](https://github.com/fern-api/fern/pull/3551)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.24.0...0.25.0-rc0](https://github.com/fern-api/fern/compare/0.24.0...0.25.0-rc0)\
\
\
# May 6, 2024\
\
## 0.24.0\
\
**`(chore):`** ## What's Changed\
\
* (fix): remove `api.yml` not found error when the openapi folder is present by @dsinghvi in [https://github.com/fern-api/fern/pull/3519](https://github.com/fern-api/fern/pull/3519)\
* add example snippet syntax by @abvthecity in [https://github.com/fern-api/fern/pull/3523](https://github.com/fern-api/fern/pull/3523)\
* (fix, internal):  fix preview docs and move props to left side in docs by @dsinghvi in [https://github.com/fern-api/fern/pull/3525](https://github.com/fern-api/fern/pull/3525)\
* fix, python: check for nulls before dereferencing in unchecked base m\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3528](https://github.com/fern-api/fern/pull/3528)\
* (feature, openapi): Add x-fern-base-path extension by @amckinney in [https://github.com/fern-api/fern/pull/3530](https://github.com/fern-api/fern/pull/3530)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.23.7...0.24.0](https://github.com/fern-api/fern/compare/0.23.7...0.24.0)\
\
\
# May 2, 2024\
\
## 0.23.7\
\
**`(chore):`** ## What's Changed\
\
* fix: The vanilla pydantic base model now respects the by @armandobelardo in [https://github.com/fern-api/fern/pull/3504](https://github.com/fern-api/fern/pull/3504)\
* (fix): support parsing path parameters in asyncapi v2 by @dsinghvi in [https://github.com/fern-api/fern/pull/3505](https://github.com/fern-api/fern/pull/3505)\
* (internal, test): Stop testing IR generation snapshots by @dsinghvi in [https://github.com/fern-api/fern/pull/3508](https://github.com/fern-api/fern/pull/3508)\
* fix, python: pipe through the whole kit and caboodle for inlined unions by @armandobelardo in [https://github.com/fern-api/fern/pull/3507](https://github.com/fern-api/fern/pull/3507)\
* fix, python: the SDK generator now generates disciminated unions correctlly by @armandobelardo in [https://github.com/fern-api/fern/pull/3509](https://github.com/fern-api/fern/pull/3509)\
* internal: release python generator RC by @armandobelardo in [https://github.com/fern-api/fern/pull/3510](https://github.com/fern-api/fern/pull/3510)\
* fix, ts, python: snippet template paper cuts by @armandobelardo in [https://github.com/fern-api/fern/pull/3511](https://github.com/fern-api/fern/pull/3511)\
* (fix, ts): Prefer user-provided examples by @amckinney in [https://github.com/fern-api/fern/pull/3496](https://github.com/fern-api/fern/pull/3496)\
* (fix, ts): Add URL encoding to path parameters by @amckinney in [https://github.com/fern-api/fern/pull/3494](https://github.com/fern-api/fern/pull/3494)\
* (docs) aside component by @dannysheridan in [https://github.com/fern-api/fern/pull/3512](https://github.com/fern-api/fern/pull/3512)\
* internal: update public api docs by @armandobelardo in [https://github.com/fern-api/fern/pull/3513](https://github.com/fern-api/fern/pull/3513)\
* (feature, ts): Add JSDoc docs to client methods by @amckinney in [https://github.com/fern-api/fern/pull/3515](https://github.com/fern-api/fern/pull/3515)\
* improvement: add in sync templates for python (in addition to async) by @armandobelardo in [https://github.com/fern-api/fern/pull/3516](https://github.com/fern-api/fern/pull/3516)\
* (chore, python): Ignore core\\_utilities in mypy by @amckinney in [https://github.com/fern-api/fern/pull/3517](https://github.com/fern-api/fern/pull/3517)\
* (feature): expose `x-fern-property-name` extension by @dsinghvi in [https://github.com/fern-api/fern/pull/3518](https://github.com/fern-api/fern/pull/3518)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.23.6...0.23.7](https://github.com/fern-api/fern/compare/0.23.6...0.23.7)\
\
\
# May 1, 2024\
\
## 0.23.4\
\
**`(chore):`** ## What's Changed\
\
* improvements, python: update docstrings to match numpydoc convention by @armandobelardo in [https://github.com/fern-api/fern/pull/3487](https://github.com/fern-api/fern/pull/3487)\
* feat, python: introduce flag to inline request params in function sig\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3491](https://github.com/fern-api/fern/pull/3491)\
* (fix, go): Add URL encoding to path parameters by @amckinney in [https://github.com/fern-api/fern/pull/3488](https://github.com/fern-api/fern/pull/3488)\
* (feat, internal): introduce default custom config and use in express generator by @dsinghvi in [https://github.com/fern-api/fern/pull/3493](https://github.com/fern-api/fern/pull/3493)\
* (fix, python): re-add inlining union properties by @armandobelardo in [https://github.com/fern-api/fern/pull/3476](https://github.com/fern-api/fern/pull/3476)\
* feat: tabs with href by @abvthecity in [https://github.com/fern-api/fern/pull/3497](https://github.com/fern-api/fern/pull/3497)\
* feat: in docs.yml, allow api reference to be "flattened" by @abvthecity in [https://github.com/fern-api/fern/pull/3498](https://github.com/fern-api/fern/pull/3498)\
* fix, ts: remove duplicate quotation marks from snippet templates by @armandobelardo in [https://github.com/fern-api/fern/pull/3495](https://github.com/fern-api/fern/pull/3495)\
* fix: address formatting issues with python templates by @armandobelardo in [https://github.com/fern-api/fern/pull/3499](https://github.com/fern-api/fern/pull/3499)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.23.3...0.23.4](https://github.com/fern-api/fern/compare/0.23.3...0.23.4)\
\
\
# April 30, 2024\
\
## 0.23.2\
\
**`(chore):`** ## What's Changed\
\
* improvement: throw a better error when an invalid version is used by @armandobelardo in [https://github.com/fern-api/fern/pull/3477](https://github.com/fern-api/fern/pull/3477)\
* (fix, go): Discrimninated unions always include discriminant by @amckinney in [https://github.com/fern-api/fern/pull/3479](https://github.com/fern-api/fern/pull/3479)\
* (internal, feat): add  mode to seed for running the generators directly from source by @dsinghvi in [https://github.com/fern-api/fern/pull/3421](https://github.com/fern-api/fern/pull/3421)\
* (fix, docs): improve docs overview by @dsinghvi in [https://github.com/fern-api/fern/pull/3480](https://github.com/fern-api/fern/pull/3480)\
* (docs, quickstart): rewrite the docs quickstart by @dsinghvi in [https://github.com/fern-api/fern/pull/3481](https://github.com/fern-api/fern/pull/3481)\
* docs: add pages for api reference navigation and summary markdown by @abvthecity in [https://github.com/fern-api/fern/pull/3482](https://github.com/fern-api/fern/pull/3482)\
* (chore): parse file upload and their descriptions by @dsinghvi in [https://github.com/fern-api/fern/pull/3485](https://github.com/fern-api/fern/pull/3485)\
* (feature, go): Add cursor and offset pagination by @amckinney in [https://github.com/fern-api/fern/pull/3486](https://github.com/fern-api/fern/pull/3486)\
* (fix): redo docs for accordion, accorodion groups, callouts, card groups, etc. by @dsinghvi in [https://github.com/fern-api/fern/pull/3489](https://github.com/fern-api/fern/pull/3489)\
* (fix, docs): document frames and endpoint req/res snippets by @dsinghvi in [https://github.com/fern-api/fern/pull/3490](https://github.com/fern-api/fern/pull/3490)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.23.1...0.23.2](https://github.com/fern-api/fern/compare/0.23.1...0.23.2)\
\
\
# April 26, 2024\
\
## 0.23.1-rc4\
\
**`(chore):`** ## What's Changed\
\
* fix: run seed to get CI to green by @armandobelardo in [https://github.com/fern-api/fern/pull/3463](https://github.com/fern-api/fern/pull/3463)\
* (feature, go): Add support for extra properties by @amckinney in [https://github.com/fern-api/fern/pull/3462](https://github.com/fern-api/fern/pull/3462)\
* fix: try ignoring the .mock folder, whos diff doesn't matter by @armandobelardo in [https://github.com/fern-api/fern/pull/3465](https://github.com/fern-api/fern/pull/3465)\
* feat: support multiple custom domains by @abvthecity in [https://github.com/fern-api/fern/pull/3466](https://github.com/fern-api/fern/pull/3466)\
* fix: migrating docs.yml to 0.15.0-rc0 should fail if custom-domain is an array by @abvthecity in [https://github.com/fern-api/fern/pull/3467](https://github.com/fern-api/fern/pull/3467)\
* (feat): introduce an audiences config to load filtered OpenAPIs  by @dsinghvi in [https://github.com/fern-api/fern/pull/3468](https://github.com/fern-api/fern/pull/3468)\
* add logging to ts snippet template generation by @armandobelardo in [https://github.com/fern-api/fern/pull/3469](https://github.com/fern-api/fern/pull/3469)\
* fix: fix indentation level for ts templates by @armandobelardo in [https://github.com/fern-api/fern/pull/3470](https://github.com/fern-api/fern/pull/3470)\
* (fix, go): Only use omitempty for nil-able types by @amckinney in [https://github.com/fern-api/fern/pull/3471](https://github.com/fern-api/fern/pull/3471)\
* (fix): backfill SSE events as streaming json by @dsinghvi in [https://github.com/fern-api/fern/pull/3472](https://github.com/fern-api/fern/pull/3472)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.23.0...0.23.1-rc4](https://github.com/fern-api/fern/compare/0.23.0...0.23.1-rc4)\
\
\
# April 25, 2024\
\
## 0.23.0\
\
**`(chore):`** ## What's Changed\
\
* (feat): add `format` to the `x-fern-streaming` extension to support sse by @dsinghvi in [https://github.com/fern-api/fern/pull/3407](https://github.com/fern-api/fern/pull/3407)\
* Revert "(fix): inline discriminated union props" by @dsinghvi in [https://github.com/fern-api/fern/pull/3408](https://github.com/fern-api/fern/pull/3408)\
* (fix): python generator imports `json` when deserializing server sent events by @dsinghvi in [https://github.com/fern-api/fern/pull/3409](https://github.com/fern-api/fern/pull/3409)\
* (feature): Add OAuth to IR by @amckinney in [https://github.com/fern-api/fern/pull/3410](https://github.com/fern-api/fern/pull/3410)\
* (feat, ts): support server-sent events by @dsinghvi in [https://github.com/fern-api/fern/pull/3411](https://github.com/fern-api/fern/pull/3411)\
* (feat, docs): create a api definition tab before sdks and docs by @dsinghvi in [https://github.com/fern-api/fern/pull/3413](https://github.com/fern-api/fern/pull/3413)\
* (fix): setup local cli by @dsinghvi in [https://github.com/fern-api/fern/pull/3416](https://github.com/fern-api/fern/pull/3416)\
* (fix): fixes trailing slash parsing in openapi-parser, updates tests by @franklinharvey in [https://github.com/fern-api/fern/pull/3418](https://github.com/fern-api/fern/pull/3418)\
* (fix): fixes trailing slash additional test by @franklinharvey in [https://github.com/fern-api/fern/pull/3419](https://github.com/fern-api/fern/pull/3419)\
* (internal, seed): heavy rewrite of seed by @dsinghvi in [https://github.com/fern-api/fern/pull/3297](https://github.com/fern-api/fern/pull/3297)\
* feat: register snippet templates by @armandobelardo in [https://github.com/fern-api/fern/pull/3400](https://github.com/fern-api/fern/pull/3400)\
* (feat): release python sdk generator by @dsinghvi in [https://github.com/fern-api/fern/pull/3423](https://github.com/fern-api/fern/pull/3423)\
* internal: add logging to python template generation by @armandobelardo in [https://github.com/fern-api/fern/pull/3424](https://github.com/fern-api/fern/pull/3424)\
* fix: fix debug log in template generator by @armandobelardo in [https://github.com/fern-api/fern/pull/3426](https://github.com/fern-api/fern/pull/3426)\
* fix, internal: leverage the union factory to create the generic templ\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3427](https://github.com/fern-api/fern/pull/3427)\
* fix, python: add best-case formatting to snippet templates by @armandobelardo in [https://github.com/fern-api/fern/pull/3428](https://github.com/fern-api/fern/pull/3428)\
* (fix, typescript): respect stream terminator by @dsinghvi in [https://github.com/fern-api/fern/pull/3429](https://github.com/fern-api/fern/pull/3429)\
* fix: use relative location for containers, not it's parent's location by @armandobelardo in [https://github.com/fern-api/fern/pull/3431](https://github.com/fern-api/fern/pull/3431)\
* fix: do not stringify null headers by @armandobelardo in [https://github.com/fern-api/fern/pull/3433](https://github.com/fern-api/fern/pull/3433)\
* fix: parse map example by @abvthecity in [https://github.com/fern-api/fern/pull/3434](https://github.com/fern-api/fern/pull/3434)\
* fix: skipUrlSlug in api section by @abvthecity in [https://github.com/fern-api/fern/pull/3435](https://github.com/fern-api/fern/pull/3435)\
* Fixes validation rules for path and base-path by @franklinharvey in [https://github.com/fern-api/fern/pull/3420](https://github.com/fern-api/fern/pull/3420)\
* (fix): get ci to green by @dsinghvi in [https://github.com/fern-api/fern/pull/3437](https://github.com/fern-api/fern/pull/3437)\
* chore, python: follow redirects by default by @armandobelardo in [https://github.com/fern-api/fern/pull/3436](https://github.com/fern-api/fern/pull/3436)\
* (feature, python): Add OAuth token provider by @amckinney in [https://github.com/fern-api/fern/pull/3439](https://github.com/fern-api/fern/pull/3439)\
* improvement, oas: do not require schema to be present to parse response objects by @armandobelardo in [https://github.com/fern-api/fern/pull/3438](https://github.com/fern-api/fern/pull/3438)\
* feat: show error schemas in docs by @abvthecity in [https://github.com/fern-api/fern/pull/3401](https://github.com/fern-api/fern/pull/3401)\
* (fix): OAuth is migrated back to bearer by @amckinney in [https://github.com/fern-api/fern/pull/3440](https://github.com/fern-api/fern/pull/3440)\
* chore: transition snippets api to monorepo by @armandobelardo in [https://github.com/fern-api/fern/pull/3442](https://github.com/fern-api/fern/pull/3442)\
* Update what-is-an-api-definition.mdx by @bsinghvi in [https://github.com/fern-api/fern/pull/3443](https://github.com/fern-api/fern/pull/3443)\
* (fix, python): OAuthTokenProvider initializes all private member variables by @amckinney in [https://github.com/fern-api/fern/pull/3444](https://github.com/fern-api/fern/pull/3444)\
* (fix): seed run with custom fixture works by @dsinghvi in [https://github.com/fern-api/fern/pull/3445](https://github.com/fern-api/fern/pull/3445)\
* (feature): Add support for extra-properties by @amckinney in [https://github.com/fern-api/fern/pull/3441](https://github.com/fern-api/fern/pull/3441)\
* chore: add a lot of logging and attempt to optimize rubocop config by @armandobelardo in [https://github.com/fern-api/fern/pull/3447](https://github.com/fern-api/fern/pull/3447)\
* (fix): ts seed debugging works by @dsinghvi in [https://github.com/fern-api/fern/pull/3446](https://github.com/fern-api/fern/pull/3446)\
* (feat): support text responses in typescript by @dsinghvi in [https://github.com/fern-api/fern/pull/3451](https://github.com/fern-api/fern/pull/3451)\
* fix: subpackage uses original name by @abvthecity in [https://github.com/fern-api/fern/pull/3452](https://github.com/fern-api/fern/pull/3452)\
* (fix, python): Use kwargs for all httpx params by @amckinney in [https://github.com/fern-api/fern/pull/3454](https://github.com/fern-api/fern/pull/3454)\
* fix: do not fail hard if FDR is having problems by @armandobelardo in [https://github.com/fern-api/fern/pull/3455](https://github.com/fern-api/fern/pull/3455)\
* (chore): Update all seed snapshots by @amckinney in [https://github.com/fern-api/fern/pull/3456](https://github.com/fern-api/fern/pull/3456)\
* (chore): Add better Python CHANGELOG.md entry by @amckinney in [https://github.com/fern-api/fern/pull/3457](https://github.com/fern-api/fern/pull/3457)\
* (fix, typescript): handle empty sse events by @dsinghvi in [https://github.com/fern-api/fern/pull/3458](https://github.com/fern-api/fern/pull/3458)\
* (improvement): appending type for type exports by @bsinghvi in [https://github.com/fern-api/fern/pull/3405](https://github.com/fern-api/fern/pull/3405)\
* Updating TS seed generated files by @bsinghvi in [https://github.com/fern-api/fern/pull/3459](https://github.com/fern-api/fern/pull/3459)\
* Fixing API First Development box link by @bsinghvi in [https://github.com/fern-api/fern/pull/3460](https://github.com/fern-api/fern/pull/3460)\
* Switching product card ordering on welcome by @bsinghvi in [https://github.com/fern-api/fern/pull/3461](https://github.com/fern-api/fern/pull/3461)\
* feat, ts: introduce snippet template creation by @armandobelardo in [https://github.com/fern-api/fern/pull/3450](https://github.com/fern-api/fern/pull/3450)\
* (fix): openapi converter handles missing schemas by @dsinghvi in [https://github.com/fern-api/fern/pull/3464](https://github.com/fern-api/fern/pull/3464)\
\
## New Contributors\
\
* @franklinharvey made their first contribution in [https://github.com/fern-api/fern/pull/3418](https://github.com/fern-api/fern/pull/3418)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.22.0...0.23.0](https://github.com/fern-api/fern/compare/0.22.0...0.23.0)\
\
\
# April 23, 2024\
\
## 0.23.0-rc4\
\
**`(chore):`** ## What's Changed\
\
* (feat): add `format` to the `x-fern-streaming` extension to support sse by @dsinghvi in [https://github.com/fern-api/fern/pull/3407](https://github.com/fern-api/fern/pull/3407)\
* Revert "(fix): inline discriminated union props" by @dsinghvi in [https://github.com/fern-api/fern/pull/3408](https://github.com/fern-api/fern/pull/3408)\
* (fix): python generator imports `json` when deserializing server sent events by @dsinghvi in [https://github.com/fern-api/fern/pull/3409](https://github.com/fern-api/fern/pull/3409)\
* (feature): Add OAuth to IR by @amckinney in [https://github.com/fern-api/fern/pull/3410](https://github.com/fern-api/fern/pull/3410)\
* (feat, ts): support server-sent events by @dsinghvi in [https://github.com/fern-api/fern/pull/3411](https://github.com/fern-api/fern/pull/3411)\
* (feat, docs): create a api definition tab before sdks and docs by @dsinghvi in [https://github.com/fern-api/fern/pull/3413](https://github.com/fern-api/fern/pull/3413)\
* (fix): setup local cli by @dsinghvi in [https://github.com/fern-api/fern/pull/3416](https://github.com/fern-api/fern/pull/3416)\
* (fix): fixes trailing slash parsing in openapi-parser, updates tests by @franklinharvey in [https://github.com/fern-api/fern/pull/3418](https://github.com/fern-api/fern/pull/3418)\
* (fix): fixes trailing slash additional test by @franklinharvey in [https://github.com/fern-api/fern/pull/3419](https://github.com/fern-api/fern/pull/3419)\
* (internal, seed): heavy rewrite of seed by @dsinghvi in [https://github.com/fern-api/fern/pull/3297](https://github.com/fern-api/fern/pull/3297)\
* feat: register snippet templates by @armandobelardo in [https://github.com/fern-api/fern/pull/3400](https://github.com/fern-api/fern/pull/3400)\
* (feat): release python sdk generator by @dsinghvi in [https://github.com/fern-api/fern/pull/3423](https://github.com/fern-api/fern/pull/3423)\
* internal: add logging to python template generation by @armandobelardo in [https://github.com/fern-api/fern/pull/3424](https://github.com/fern-api/fern/pull/3424)\
* fix: fix debug log in template generator by @armandobelardo in [https://github.com/fern-api/fern/pull/3426](https://github.com/fern-api/fern/pull/3426)\
* fix, internal: leverage the union factory to create the generic templ\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3427](https://github.com/fern-api/fern/pull/3427)\
* fix, python: add best-case formatting to snippet templates by @armandobelardo in [https://github.com/fern-api/fern/pull/3428](https://github.com/fern-api/fern/pull/3428)\
* (fix, typescript): respect stream terminator by @dsinghvi in [https://github.com/fern-api/fern/pull/3429](https://github.com/fern-api/fern/pull/3429)\
* fix: use relative location for containers, not it's parent's location by @armandobelardo in [https://github.com/fern-api/fern/pull/3431](https://github.com/fern-api/fern/pull/3431)\
* fix: do not stringify null headers by @armandobelardo in [https://github.com/fern-api/fern/pull/3433](https://github.com/fern-api/fern/pull/3433)\
* fix: parse map example by @abvthecity in [https://github.com/fern-api/fern/pull/3434](https://github.com/fern-api/fern/pull/3434)\
* fix: skipUrlSlug in api section by @abvthecity in [https://github.com/fern-api/fern/pull/3435](https://github.com/fern-api/fern/pull/3435)\
* Fixes validation rules for path and base-path by @franklinharvey in [https://github.com/fern-api/fern/pull/3420](https://github.com/fern-api/fern/pull/3420)\
* (fix): get ci to green by @dsinghvi in [https://github.com/fern-api/fern/pull/3437](https://github.com/fern-api/fern/pull/3437)\
\
## New Contributors\
\
* @franklinharvey made their first contribution in [https://github.com/fern-api/fern/pull/3418](https://github.com/fern-api/fern/pull/3418)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.22.0...0.23.0-rc4](https://github.com/fern-api/fern/compare/0.22.0...0.23.0-rc4)\
\
\
# April 19, 2024\
\
## 0.22.0\
\
**`(chore):`** ## What's Changed\
\
* (chore, docs): document automated registry publishing) by @dsinghvi in [https://github.com/fern-api/fern/pull/3379](https://github.com/fern-api/fern/pull/3379)\
* (feature): Add allowExtraFields configuration to TypeScript generators by @amckinney in [https://github.com/fern-api/fern/pull/3368](https://github.com/fern-api/fern/pull/3368)\
* fix: address parsed\\_json instantiation for serializable object types by @armandobelardo in [https://github.com/fern-api/fern/pull/3382](https://github.com/fern-api/fern/pull/3382)\
* Fix typo in SDK docs page by @zachkirsch in [https://github.com/fern-api/fern/pull/3383](https://github.com/fern-api/fern/pull/3383)\
* (chore): upgrade fern version by @dannysheridan in [https://github.com/fern-api/fern/pull/3376](https://github.com/fern-api/fern/pull/3376)\
* fix: support multiple request and response examples automatically by @abvthecity in [https://github.com/fern-api/fern/pull/3384](https://github.com/fern-api/fern/pull/3384)\
* (fix): discriminated union schema examples don't contain discriminants by @dsinghvi in [https://github.com/fern-api/fern/pull/3386](https://github.com/fern-api/fern/pull/3386)\
* (fix): make sure versioned tabbed config works by @dsinghvi in [https://github.com/fern-api/fern/pull/3387](https://github.com/fern-api/fern/pull/3387)\
* (fix): Go path parameter order by @amckinney in [https://github.com/fern-api/fern/pull/3385](https://github.com/fern-api/fern/pull/3385)\
* (feature): Go supports environment variable scanning by @amckinney in [https://github.com/fern-api/fern/pull/3389](https://github.com/fern-api/fern/pull/3389)\
* (fix): only generate unit tests when enabled by @dsinghvi in [https://github.com/fern-api/fern/pull/3390](https://github.com/fern-api/fern/pull/3390)\
* (fix): update `node-fetch` import to be dynamic by @dsinghvi in [https://github.com/fern-api/fern/pull/3391](https://github.com/fern-api/fern/pull/3391)\
* (fix): Generate TS snippets for file download by @bsinghvi in [https://github.com/fern-api/fern/pull/3394](https://github.com/fern-api/fern/pull/3394)\
* (feat): support sse with arbitrary terminators by @dsinghvi in [https://github.com/fern-api/fern/pull/3395](https://github.com/fern-api/fern/pull/3395)\
* (improvement): add return type for getAuthorizationHeader by @bsinghvi in [https://github.com/fern-api/fern/pull/3396](https://github.com/fern-api/fern/pull/3396)\
* (feat): make module imports directly point to index.js by @dsinghvi in [https://github.com/fern-api/fern/pull/3397](https://github.com/fern-api/fern/pull/3397)\
* (fix): generate basic tests when integration tests disabled by @dsinghvi in [https://github.com/fern-api/fern/pull/3398](https://github.com/fern-api/fern/pull/3398)\
* (fix, typescript): do file upload snippet generation by @dsinghvi in [https://github.com/fern-api/fern/pull/3399](https://github.com/fern-api/fern/pull/3399)\
* (feature): Add OAuth YAML and validator by @amckinney in [https://github.com/fern-api/fern/pull/3403](https://github.com/fern-api/fern/pull/3403)\
* (feat, python): support sse by @dsinghvi in [https://github.com/fern-api/fern/pull/3402](https://github.com/fern-api/fern/pull/3402)\
* (fix): inline discriminated union props by @dsinghvi in [https://github.com/fern-api/fern/pull/3404](https://github.com/fern-api/fern/pull/3404)\
\
## New Contributors\
\
* @bsinghvi made their first contribution in [https://github.com/fern-api/fern/pull/3394](https://github.com/fern-api/fern/pull/3394)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.21.0...0.22.0](https://github.com/fern-api/fern/compare/0.21.0...0.22.0)\
\
\
# April 15, 2024\
\
## 0.21.0\
\
**`(chore):`** ## What's Changed\
\
* improvements: misc ruby QOL changes by @armandobelardo in [https://github.com/fern-api/fern/pull/3349](https://github.com/fern-api/fern/pull/3349)\
* fix readme links to images that were moved from /docs/images by @harry-humanloop in [https://github.com/fern-api/fern/pull/3355](https://github.com/fern-api/fern/pull/3355)\
* additional ruby fixes to the 0.5.0 overhaul by @armandobelardo in [https://github.com/fern-api/fern/pull/3359](https://github.com/fern-api/fern/pull/3359)\
* (chore): setup docs landing page by @dsinghvi in [https://github.com/fern-api/fern/pull/3361](https://github.com/fern-api/fern/pull/3361)\
* (feature): Implement fern generate --preview by @amckinney in [https://github.com/fern-api/fern/pull/3363](https://github.com/fern-api/fern/pull/3363)\
* chore: add learn to welcome links hrefs by @dannysheridan in [https://github.com/fern-api/fern/pull/3369](https://github.com/fern-api/fern/pull/3369)\
* build(deps): bump tar from 4.4.19 to 6.2.1 by @dependabot in [https://github.com/fern-api/fern/pull/3348](https://github.com/fern-api/fern/pull/3348)\
* fix, ruby: call json.parse before iterating through response by @armandobelardo in [https://github.com/fern-api/fern/pull/3367](https://github.com/fern-api/fern/pull/3367)\
* feat: introduce snippets for Ruby SDKs by @armandobelardo in [https://github.com/fern-api/fern/pull/3370](https://github.com/fern-api/fern/pull/3370)\
* (chore): fix title in front matter for docs by @dannysheridan in [https://github.com/fern-api/fern/pull/3375](https://github.com/fern-api/fern/pull/3375)\
* improvement: pass snippets version to fdr to register docs with snippets at a specific version by @armandobelardo in [https://github.com/fern-api/fern/pull/3374](https://github.com/fern-api/fern/pull/3374)\
* (feat): redo SDKs documentation by @dsinghvi in [https://github.com/fern-api/fern/pull/3365](https://github.com/fern-api/fern/pull/3365)\
* (feat, docs): explain registering and depending on api artifacts by @dsinghvi in [https://github.com/fern-api/fern/pull/3377](https://github.com/fern-api/fern/pull/3377)\
* fix: update IR for the TS SDK by @armandobelardo in [https://github.com/fern-api/fern/pull/3378](https://github.com/fern-api/fern/pull/3378)\
\
## New Contributors\
\
* @harry-humanloop made their first contribution in [https://github.com/fern-api/fern/pull/3355](https://github.com/fern-api/fern/pull/3355)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.20.0...0.21.0](https://github.com/fern-api/fern/compare/0.20.0...0.21.0)\
\
\
# April 10, 2024\
\
## 0.20.0\
\
**`(chore):`** ## What's Changed\
\
* (fix): code blocks are valid by @dsinghvi in [https://github.com/fern-api/fern/pull/3337](https://github.com/fern-api/fern/pull/3337)\
* improvement, ruby: add and run rake to run dummy test for build errors by @armandobelardo in [https://github.com/fern-api/fern/pull/3330](https://github.com/fern-api/fern/pull/3330)\
* add api origin to generators config by @armandobelardo in [https://github.com/fern-api/fern/pull/3336](https://github.com/fern-api/fern/pull/3336)\
* build(deps): bump github.com/fern-api/generator-exec-go from 0.0.694 to 0.0.702 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3342](https://github.com/fern-api/fern/pull/3342)\
* build(deps): bump golang.org/x/mod from 0.16.0 to 0.17.0 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3341](https://github.com/fern-api/fern/pull/3341)\
* build(deps): bump golang.org/x/tools from 0.19.0 to 0.20.0 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3340](https://github.com/fern-api/fern/pull/3340)\
* build(deps-dev): bump vite from 5.1.3 to 5.2.8 by @dependabot in [https://github.com/fern-api/fern/pull/3339](https://github.com/fern-api/fern/pull/3339)\
* fix: allow lists and sets to be complex query params by @armandobelardo in [https://github.com/fern-api/fern/pull/3343](https://github.com/fern-api/fern/pull/3343)\
* Update README to point to the latest generators by @armandobelardo in [https://github.com/fern-api/fern/pull/3344](https://github.com/fern-api/fern/pull/3344)\
* fix: commit .mock in ts-sdk by @mscolnick in [https://github.com/fern-api/fern/pull/3345](https://github.com/fern-api/fern/pull/3345)\
* feat: generated jest tests by @mscolnick in [https://github.com/fern-api/fern/pull/3267](https://github.com/fern-api/fern/pull/3267)\
* (fix): misc edits to csharp client generation by @dsinghvi in [https://github.com/fern-api/fern/pull/3335](https://github.com/fern-api/fern/pull/3335)\
* improvement: upgrade ts-sdk, ts-express to IR37 by @mscolnick in [https://github.com/fern-api/fern/pull/3347](https://github.com/fern-api/fern/pull/3347)\
* feat: add api summary markdown pages by @abvthecity in [https://github.com/fern-api/fern/pull/3350](https://github.com/fern-api/fern/pull/3350)\
* feat: hidden, skipurlslug, and icon by @abvthecity in [https://github.com/fern-api/fern/pull/3352](https://github.com/fern-api/fern/pull/3352)\
* (feat): setup root and sub client instantiations  by @dsinghvi in [https://github.com/fern-api/fern/pull/3351](https://github.com/fern-api/fern/pull/3351)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.31...0.20.0-rc0](https://github.com/fern-api/fern/compare/0.19.31...0.20.0-rc0)\
\
* (chore): changelog dates are ready based on mdx title by @dsinghvi in [https://github.com/fern-api/fern/pull/3354](https://github.com/fern-api/fern/pull/3354)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.31...0.20.0](https://github.com/fern-api/fern/compare/0.19.31...0.20.0)\
\
\
# April 5, 2024\
\
## 0.19.31\
\
**`(chore):`** ## What's Changed\
\
* revert: python generator version 0.13.2 by @armandobelardo in [https://github.com/fern-api/fern/pull/3316](https://github.com/fern-api/fern/pull/3316)\
* break: release python generator 1.x by @armandobelardo in [https://github.com/fern-api/fern/pull/3312](https://github.com/fern-api/fern/pull/3312)\
* fix: force pydantic.v1 only if pydantic v2, this is needed due to a p\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3318](https://github.com/fern-api/fern/pull/3318)\
* feat: add flag to disable Pydantic validation and keep extra fields on the Pydantic model by @armandobelardo in [https://github.com/fern-api/fern/pull/3311](https://github.com/fern-api/fern/pull/3311)\
* fix: do not try to generate the version file if we're not generating \'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3320](https://github.com/fern-api/fern/pull/3320)\
* fix: write skipping validation code the same as before to keep new lines by @armandobelardo in [https://github.com/fern-api/fern/pull/3321](https://github.com/fern-api/fern/pull/3321)\
* (chore): bump csharp sdk generator version by @dsinghvi in [https://github.com/fern-api/fern/pull/3322](https://github.com/fern-api/fern/pull/3322)\
* (feat, csharp): generate subclient files by @dsinghvi in [https://github.com/fern-api/fern/pull/3325](https://github.com/fern-api/fern/pull/3325)\
* (fix): misc c# fixes by @dsinghvi in [https://github.com/fern-api/fern/pull/3326](https://github.com/fern-api/fern/pull/3326)\
* (fix): csharp generator handles property and field level conflicts by @dsinghvi in [https://github.com/fern-api/fern/pull/3327](https://github.com/fern-api/fern/pull/3327)\
* (fix): remove str enum from c# by @dsinghvi in [https://github.com/fern-api/fern/pull/3328](https://github.com/fern-api/fern/pull/3328)\
* fix: fix pydantic skip validation by @armandobelardo in [https://github.com/fern-api/fern/pull/3324](https://github.com/fern-api/fern/pull/3324)\
* (feature): Generate snippets locally by @amckinney in [https://github.com/fern-api/fern/pull/3323](https://github.com/fern-api/fern/pull/3323)\
* (fix): send multipart upload property descriptions when registering docs by @dsinghvi in [https://github.com/fern-api/fern/pull/3333](https://github.com/fern-api/fern/pull/3333)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.30...0.19.31-rc0](https://github.com/fern-api/fern/compare/0.19.30...0.19.31-rc0)\
\
\
# April 3, 2024\
\
## 0.19.29\
\
**`(chore):`** ## What's Changed\
\
* (feature): Add retainOriginalCasing option to TypeScript generators by @amckinney in [https://github.com/fern-api/fern/pull/3310](https://github.com/fern-api/fern/pull/3310)\
* (feature): Implement pagination by @amckinney in [https://github.com/fern-api/fern/pull/3304](https://github.com/fern-api/fern/pull/3304)\
* fix: revert to one ci file in python by @armandobelardo in [https://github.com/fern-api/fern/pull/3237](https://github.com/fern-api/fern/pull/3237)\
* (fix): Authorization header schemes aren't truncated by @amckinney in [https://github.com/fern-api/fern/pull/3313](https://github.com/fern-api/fern/pull/3313)\
* (fix): pass through correct maven url by @dsinghvi in [https://github.com/fern-api/fern/pull/3315](https://github.com/fern-api/fern/pull/3315)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.28...0.19.29](https://github.com/fern-api/fern/compare/0.19.28...0.19.29)\
\
\
# April 2, 2024\
\
## 0.19.27\
\
**`(chore):`** ## What's Changed\
\
* (chore): no icon tabs by @dsinghvi in [https://github.com/fern-api/fern/pull/3309](https://github.com/fern-api/fern/pull/3309)\
* fix: allow for specifying x-fern-examples as the yaml schema, not jus\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3308](https://github.com/fern-api/fern/pull/3308)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.26...0.19.27](https://github.com/fern-api/fern/compare/0.19.26...0.19.27)\
\
\
# April 1, 2024\
\
## 0.19.25\
\
**`(chore):`** ## What's Changed\
\
* improvement: allow header auth extension to specify auth prefix by @armandobelardo in [https://github.com/fern-api/fern/pull/3303](https://github.com/fern-api/fern/pull/3303)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.24...0.19.25](https://github.com/fern-api/fern/compare/0.19.24...0.19.25)\
\
\
# March 29, 2024\
\
## 0.19.23\
\
**`(chore):`** ## What's Changed\
\
* (chore): introduce  to plumb through display name by @dsinghvi in [https://github.com/fern-api/fern/pull/3290](https://github.com/fern-api/fern/pull/3290)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.22...0.19.23](https://github.com/fern-api/fern/compare/0.19.22...0.19.23)\
\
\
# March 28, 2024\
\
## 0.19.21\
\
**`(chore):`** ## What's Changed\
\
* feat: API navigation overrides by @abvthecity in [https://github.com/fern-api/fern/pull/3205](https://github.com/fern-api/fern/pull/3205)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.20...0.19.21](https://github.com/fern-api/fern/compare/0.19.20...0.19.21)\
\
\
# March 27, 2024\
\
## 0.19.20\
\
**`(chore):`** ## What's Changed\
\
* improvement, python: add **version** variable by @armandobelardo in [https://github.com/fern-api/fern/pull/3262](https://github.com/fern-api/fern/pull/3262)\
* (docs): update fern cli commands docs by @minaelee in [https://github.com/fern-api/fern/pull/3215](https://github.com/fern-api/fern/pull/3215)\
* build(deps-dev): bump eslint-plugin-react from 7.31.10 to 7.34.1 by @dependabot in [https://github.com/fern-api/fern/pull/3264](https://github.com/fern-api/fern/pull/3264)\
* build(deps): bump github.com/fern-api/generator-exec-go from 0.0.679 to 0.0.694 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3263](https://github.com/fern-api/fern/pull/3263)\
* (docs): add requirements and installation instructions to fern CLI overview by @minaelee in [https://github.com/fern-api/fern/pull/3269](https://github.com/fern-api/fern/pull/3269)\
* (docs): preface all internal links with learn/ by @minaelee in [https://github.com/fern-api/fern/pull/3270](https://github.com/fern-api/fern/pull/3270)\
* build(deps): bump tar and @types/tar by @dependabot in [https://github.com/fern-api/fern/pull/3266](https://github.com/fern-api/fern/pull/3266)\
* build(deps-dev): bump sass from 1.71.0 to 1.72.0 by @dependabot in [https://github.com/fern-api/fern/pull/3265](https://github.com/fern-api/fern/pull/3265)\
* (fix): resolve fern check failures due to invalid enum name overrides and complex query params by @omarrida in [https://github.com/fern-api/fern/pull/3268](https://github.com/fern-api/fern/pull/3268)\
* (docs): additional internal link updates by @minaelee in [https://github.com/fern-api/fern/pull/3275](https://github.com/fern-api/fern/pull/3275)\
* build(deps): bump express from 4.18.2 to 4.19.2 by @dependabot in [https://github.com/fern-api/fern/pull/3271](https://github.com/fern-api/fern/pull/3271)\
* (docs): start react components docs by @minaelee in [https://github.com/fern-api/fern/pull/3276](https://github.com/fern-api/fern/pull/3276)\
* (docs): run vale linter on PR to fern/docs/pages/ by @minaelee in [https://github.com/fern-api/fern/pull/3274](https://github.com/fern-api/fern/pull/3274)\
* fix: make map mutable for adding environment variables by @armandobelardo in [https://github.com/fern-api/fern/pull/3280](https://github.com/fern-api/fern/pull/3280)\
* improvement: default literal values for unions by @armandobelardo in [https://github.com/fern-api/fern/pull/3283](https://github.com/fern-api/fern/pull/3283)\
* (fix): Maps are complex query params by @amckinney in [https://github.com/fern-api/fern/pull/3285](https://github.com/fern-api/fern/pull/3285)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.19...0.19.20](https://github.com/fern-api/fern/compare/0.19.19...0.19.20)\
\
\
# March 25, 2024\
\
## 0.19.19\
\
**`(chore):`** ## What's Changed\
\
* (fix): docs for `optionalImplementation` use the right key by @dsinghvi in [https://github.com/fern-api/fern/pull/3254](https://github.com/fern-api/fern/pull/3254)\
* (fix): support schema references in OpenAPI that aren't just Schema Ids by @omarrida in [https://github.com/fern-api/fern/pull/3259](https://github.com/fern-api/fern/pull/3259)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.18...0.19.19](https://github.com/fern-api/fern/compare/0.19.18...0.19.19)\
\
\
# March 23, 2024\
\
## 0.19.18\
\
**`(chore):`** ## What's Changed\
\
* fix: update python defaults to be the user provided number and not th\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3248](https://github.com/fern-api/fern/pull/3248)\
* fix depth check to prevent max call stack exceeded issue by @omarrida in [https://github.com/fern-api/fern/pull/3247](https://github.com/fern-api/fern/pull/3247)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.17...0.19.18](https://github.com/fern-api/fern/compare/0.19.17...0.19.18)\
\
\
# March 22, 2024\
\
## 0.19.17\
\
**`(chore):`** ## What's Changed\
\
* (fix): fix typo in writing license by @armandobelardo in [https://github.com/fern-api/fern/pull/3245](https://github.com/fern-api/fern/pull/3245)\
* (internal): consolidate GeneratorNotificationService implementations by @omarrida in [https://github.com/fern-api/fern/pull/3235](https://github.com/fern-api/fern/pull/3235)\
* (feature): merge x-codeSamples with x-fern-examples by @abvthecity in [https://github.com/fern-api/fern/pull/3246](https://github.com/fern-api/fern/pull/3246)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.16...0.19.17](https://github.com/fern-api/fern/compare/0.19.16...0.19.17)\
\
\
# March 21, 2024\
\
## 0.19.14\
\
**`(chore):`** ## What's Changed\
\
* (feature): sdk endpoint by @dsinghvi in [https://github.com/fern-api/fern/pull/3197](https://github.com/fern-api/fern/pull/3197)\
* feat: add in gpg signing for gradle publish by @armandobelardo in [https://github.com/fern-api/fern/pull/3195](https://github.com/fern-api/fern/pull/3195)\
* FER-970: Improve performance in by reducing reliance on async behavior and lazy dynamic imports by @omarrida in [https://github.com/fern-api/fern/pull/3206](https://github.com/fern-api/fern/pull/3206)\
* (fix): ts sdk doesn't support response property by @dsinghvi in [https://github.com/fern-api/fern/pull/3208](https://github.com/fern-api/fern/pull/3208)\
* (internal): `seed` runs whenever `seed.yml` config changes by @dsinghvi in [https://github.com/fern-api/fern/pull/3209](https://github.com/fern-api/fern/pull/3209)\
* fix: fullSlug implementation uses the wrong filepath structure by @abvthecity in [https://github.com/fern-api/fern/pull/3210](https://github.com/fern-api/fern/pull/3210)\
* (docs): remove \\$ sign from bash codeblocks content by @minaelee in [https://github.com/fern-api/fern/pull/3194](https://github.com/fern-api/fern/pull/3194)\
* add background-image docs by @minaelee in [https://github.com/fern-api/fern/pull/3211](https://github.com/fern-api/fern/pull/3211)\
* build(deps-dev): bump @ts-morph/common from 0.21.0 to 0.23.0 by @dependabot in [https://github.com/fern-api/fern/pull/3202](https://github.com/fern-api/fern/pull/3202)\
* build(deps-dev): bump eslint-plugin-tailwindcss from 3.14.2 to 3.15.1 by @dependabot in [https://github.com/fern-api/fern/pull/3201](https://github.com/fern-api/fern/pull/3201)\
* build(deps): bump github.com/fern-api/generator-exec-go from 0.0.622 to 0.0.679 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3199](https://github.com/fern-api/fern/pull/3199)\
* (feat): set `ir-version` override when running generators by @dsinghvi in [https://github.com/fern-api/fern/pull/3212](https://github.com/fern-api/fern/pull/3212)\
* bump fern version by @minaelee in [https://github.com/fern-api/fern/pull/3214](https://github.com/fern-api/fern/pull/3214)\
* improvement: allow ruby and python to take in byte streams by @armandobelardo in [https://github.com/fern-api/fern/pull/3207](https://github.com/fern-api/fern/pull/3207)\
* improvement: use AnyStr to keep intellisense for enums but allow forw\'85 by @armandobelardo in [https://github.com/fern-api/fern/pull/3216](https://github.com/fern-api/fern/pull/3216)\
* (fix): Handle optional multipart references by @amckinney in [https://github.com/fern-api/fern/pull/3218](https://github.com/fern-api/fern/pull/3218)\
* (fix): update generator config deserialization logic in OpenAPI generator by @omarrida in [https://github.com/fern-api/fern/pull/3224](https://github.com/fern-api/fern/pull/3224)\
* (internal): document syntax highlighting by @abvthecity in [https://github.com/fern-api/fern/pull/3220](https://github.com/fern-api/fern/pull/3220)\
* (chore): Simplify heading for `max height` in a code block by @dsinghvi in [https://github.com/fern-api/fern/pull/3225](https://github.com/fern-api/fern/pull/3225)\
* (chore): rename `syntax highlighting` to `code snippets` by @dsinghvi in [https://github.com/fern-api/fern/pull/3226](https://github.com/fern-api/fern/pull/3226)\
* (docs): move `searchbar` to top to create more space by @dsinghvi in [https://github.com/fern-api/fern/pull/3227](https://github.com/fern-api/fern/pull/3227)\
* fix: add signature to the local zod schema as well by @armandobelardo in [https://github.com/fern-api/fern/pull/3228](https://github.com/fern-api/fern/pull/3228)\
\
## New Contributors\
\
* @omarrida made their first contribution in [https://github.com/fern-api/fern/pull/3206](https://github.com/fern-api/fern/pull/3206)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.13...0.19.14-rc3](https://github.com/fern-api/fern/compare/0.19.13...0.19.14-rc3)\
\
\
# March 19, 2024\
\
## 0.19.14-rc0\
\
**`(chore):`** ## What's Changed\
\
* (feature): sdk endpoint by @dsinghvi in [https://github.com/fern-api/fern/pull/3197](https://github.com/fern-api/fern/pull/3197)\
* feat: add in gpg signing for gradle publish by @armandobelardo in [https://github.com/fern-api/fern/pull/3195](https://github.com/fern-api/fern/pull/3195)\
* FER-970: Improve performance in by reducing reliance on async behavior and lazy dynamic imports by @omarrida in [https://github.com/fern-api/fern/pull/3206](https://github.com/fern-api/fern/pull/3206)\
* (fix): ts sdk doesn't support response property by @dsinghvi in [https://github.com/fern-api/fern/pull/3208](https://github.com/fern-api/fern/pull/3208)\
* (internal): `seed` runs whenever `seed.yml` config changes by @dsinghvi in [https://github.com/fern-api/fern/pull/3209](https://github.com/fern-api/fern/pull/3209)\
* fix: fullSlug implementation uses the wrong filepath structure by @abvthecity in [https://github.com/fern-api/fern/pull/3210](https://github.com/fern-api/fern/pull/3210)\
* (docs): remove \\$ sign from bash codeblocks content by @minaelee in [https://github.com/fern-api/fern/pull/3194](https://github.com/fern-api/fern/pull/3194)\
* add background-image docs by @minaelee in [https://github.com/fern-api/fern/pull/3211](https://github.com/fern-api/fern/pull/3211)\
* build(deps-dev): bump @ts-morph/common from 0.21.0 to 0.23.0 by @dependabot in [https://github.com/fern-api/fern/pull/3202](https://github.com/fern-api/fern/pull/3202)\
* build(deps-dev): bump eslint-plugin-tailwindcss from 3.14.2 to 3.15.1 by @dependabot in [https://github.com/fern-api/fern/pull/3201](https://github.com/fern-api/fern/pull/3201)\
* build(deps): bump github.com/fern-api/generator-exec-go from 0.0.622 to 0.0.679 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3199](https://github.com/fern-api/fern/pull/3199)\
\
## New Contributors\
\
* @omarrida made their first contribution in [https://github.com/fern-api/fern/pull/3206](https://github.com/fern-api/fern/pull/3206)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.13...0.19.14-rc0](https://github.com/fern-api/fern/compare/0.19.13...0.19.14-rc0)\
\
\
# March 18, 2024\
\
## 0.19.12\
\
**`(chore):`** ## What's Changed\
\
* (fix): unit tests for python now run successfully by @armandobelardo in [https://github.com/fern-api/fern/pull/3187](https://github.com/fern-api/fern/pull/3187)\
* (improvement): allow x-fern-sdk-group-name to be a list by @mscolnick in [https://github.com/fern-api/fern/pull/3196](https://github.com/fern-api/fern/pull/3196)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.11...0.19.12](https://github.com/fern-api/fern/compare/0.19.11...0.19.12)\
\
\
# March 15, 2024\
\
## 0.19.10\
\
**`(chore):`** ## What's Changed\
\
* fix: add in envvar scanning for more than bearer auth by @armandobelardo in [https://github.com/fern-api/fern/pull/3176](https://github.com/fern-api/fern/pull/3176)\
* fixing unit tests by @armandobelardo in [https://github.com/fern-api/fern/pull/3168](https://github.com/fern-api/fern/pull/3168)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.9...0.19.10](https://github.com/fern-api/fern/compare/0.19.9...0.19.10)\
\
\
# March 13, 2024\
\
## 0.19.7\
\
**`(chore):`** ## What's Changed\
\
* feat: init c# playground by @armandobelardo in [https://github.com/fern-api/fern/pull/3142](https://github.com/fern-api/fern/pull/3142)\
* build(deps-dev): bump eslint-plugin-tailwindcss from 3.13.0 to 3.13.1 by @dependabot in [https://github.com/fern-api/fern/pull/2946](https://github.com/fern-api/fern/pull/2946)\
* (chore): consolidate configuration into single package by @dsinghvi in [https://github.com/fern-api/fern/pull/3141](https://github.com/fern-api/fern/pull/3141)\
* (feature): fern check catches invalid mdx files in docs by @dsinghvi in [https://github.com/fern-api/fern/pull/3145](https://github.com/fern-api/fern/pull/3145)\
* (feature): convert markdown references to slug if possible by @dsinghvi in [https://github.com/fern-api/fern/pull/3146](https://github.com/fern-api/fern/pull/3146)\
* fix: do not add auto-example if one exists by @armandobelardo in [https://github.com/fern-api/fern/pull/3147](https://github.com/fern-api/fern/pull/3147)\
* (fix): migration depends on published coordinate by @dsinghvi in [https://github.com/fern-api/fern/pull/3143](https://github.com/fern-api/fern/pull/3143)\
* import float as unknown from openapi spec by @buie in [https://github.com/fern-api/fern/pull/3144](https://github.com/fern-api/fern/pull/3144)\
* chore: add polling to feature spec by @armandobelardo in [https://github.com/fern-api/fern/pull/3068](https://github.com/fern-api/fern/pull/3068)\
* build(deps): bump golang.org/x/tools from 0.18.0 to 0.19.0 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3151](https://github.com/fern-api/fern/pull/3151)\
* build(deps): bump github.com/fern-api/generator-exec-go from 0.0.609 to 0.0.622 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3150](https://github.com/fern-api/fern/pull/3150)\
* (feature): implement fileUpload and bytes type conversion to FDR by @abvthecity in [https://github.com/fern-api/fern/pull/3158](https://github.com/fern-api/fern/pull/3158)\
* feat, python: add snippet-based testing to Python SDKs by @armandobelardo in [https://github.com/fern-api/fern/pull/3102](https://github.com/fern-api/fern/pull/3102)\
* (fix): enable SSO on preview URLs by @abvthecity in [https://github.com/fern-api/fern/pull/3160](https://github.com/fern-api/fern/pull/3160)\
* (fix): Go snippets handle unknown examples by @amckinney in [https://github.com/fern-api/fern/pull/3163](https://github.com/fern-api/fern/pull/3163)\
* (fix): update IR migration gates for Python SDK by @dsinghvi in [https://github.com/fern-api/fern/pull/3164](https://github.com/fern-api/fern/pull/3164)\
\
## New Contributors\
\
* @buie made their first contribution in [https://github.com/fern-api/fern/pull/3144](https://github.com/fern-api/fern/pull/3144)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.6...0.19.7-rc0](https://github.com/fern-api/fern/compare/0.19.6...0.19.7-rc0)\
\
\
# March 10, 2024\
\
## 0.19.5\
\
**`(chore):`** ## What's Changed\
\
* (feat, cli): add autogenerated examples for the fern definition by @armandobelardo in [https://github.com/fern-api/fern/pull/3114](https://github.com/fern-api/fern/pull/3114)\
* (fix, cli): don't require a schema to exist under `application/octet-stream` by @armandobelardo in [https://github.com/fern-api/fern/pull/3137](https://github.com/fern-api/fern/pull/3137)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.4...0.19.5](https://github.com/fern-api/fern/compare/0.19.4...0.19.5)\
\
\
# March 9, 2024\
\
## 0.19.4\
\
**`(chore):`** ## What's Changed\
\
* feat, python: allow extra fields not specified in model to come through by @armandobelardo in [https://github.com/fern-api/fern/pull/3131](https://github.com/fern-api/fern/pull/3131)\
* (fix): `x-fern-streaming` wont duplicate referenced requests causing collision by @dsinghvi in [https://github.com/fern-api/fern/pull/3136](https://github.com/fern-api/fern/pull/3136)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.3...0.19.4](https://github.com/fern-api/fern/compare/0.19.3...0.19.4)\
\
\
# March 8, 2024\
\
## 0.19.1\
\
**`(chore):`** ## What's Changed\
\
* (fix): detect file object in OpenAPI and ignore content type by @dsinghvi in [https://github.com/fern-api/fern/pull/3128](https://github.com/fern-api/fern/pull/3128)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.0...0.19.1](https://github.com/fern-api/fern/compare/0.19.0...0.19.1)\
\
\
# March 7, 2024\
\
## 0.19.0-rc8\
\
**`(chore):`** ## What's Changed\
\
* (improvement, python): add additional reserved words to python by @armandobelardo in [https://github.com/fern-api/fern/pull/3116](https://github.com/fern-api/fern/pull/3116)\
* (chore): fix our tests by @dsinghvi in [https://github.com/fern-api/fern/pull/3119](https://github.com/fern-api/fern/pull/3119)\
* (fix): `fern generate --docs` doesn't reupload duplicate files preventing 503s by @dsinghvi in [https://github.com/fern-api/fern/pull/3120](https://github.com/fern-api/fern/pull/3120)\
* (feature): introduce more layout options for docs configuration by @abvthecity in [https://github.com/fern-api/fern/pull/3115](https://github.com/fern-api/fern/pull/3115)\
* (beta): introduce new api configuration in generators.yml by @dsinghvi in [https://github.com/fern-api/fern/pull/3121](https://github.com/fern-api/fern/pull/3121)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.0-rc7...0.19.0-rc8](https://github.com/fern-api/fern/compare/0.19.0-rc7...0.19.0-rc8)\
\
\
# March 5, 2024\
\
## 0.19.0-rc6\
\
**`(chore):`** ## What's Changed\
\
* (fix, python): use docstrings instead of descriptions by @armandobelardo in [https://github.com/fern-api/fern/pull/3108](https://github.com/fern-api/fern/pull/3108)\
* (feature, go): Supports simpler unions by @amckinney in [https://github.com/fern-api/fern/pull/3111](https://github.com/fern-api/fern/pull/3111)\
* (fix, cli): strip trailing slash from environments list by @abvthecity in [https://github.com/fern-api/fern/pull/3109](https://github.com/fern-api/fern/pull/3109)\
* (feature): allow overriding type for global headers by @dsinghvi in [https://github.com/fern-api/fern/pull/3101](https://github.com/fern-api/fern/pull/3101)\
* (feat, python): add in max\\_retries with exponential backoff by @armandobelardo in [https://github.com/fern-api/fern/pull/3096](https://github.com/fern-api/fern/pull/3096)\
* (ts, feature): introduce custom config for `tolerateRepublish` to re publish npm versions by @dsinghvi in [https://github.com/fern-api/fern/pull/3093](https://github.com/fern-api/fern/pull/3093)\
* (improvement, python): swap to literals instead of enums by @armandobelardo in [https://github.com/fern-api/fern/pull/3082](https://github.com/fern-api/fern/pull/3082)\
* (fix, python): support generating correct code snippets when extending base client in python by @dsinghvi in [https://github.com/fern-api/fern/pull/3097](https://github.com/fern-api/fern/pull/3097)\
* (fix): Importer handles adding imports from api.yml  by @dsinghvi in [https://github.com/fern-api/fern/pull/3100](https://github.com/fern-api/fern/pull/3100)\
* (fix, ruby): add missing ruby dependencies to ensure rubocop can install by @armandobelardo in [https://github.com/fern-api/fern/pull/3090](https://github.com/fern-api/fern/pull/3090)\
* (fix, ts): leverage the full package path for `reference.md` by @armandobelardo in [https://github.com/fern-api/fern/pull/3083](https://github.com/fern-api/fern/pull/3083)\
* (feature): Add option to disable OpenAPI example generation by @amckinney in [https://github.com/fern-api/fern/pull/3091](https://github.com/fern-api/fern/pull/3091)\
* (feature): leverage OpenAPI extension `x-tags` for schemas by @dsinghvi in [https://github.com/fern-api/fern/pull/3081](https://github.com/fern-api/fern/pull/3081)\
* (fix, typescript): serialize optional deep object query params correctly in the TypeScript SDK  by @dsinghvi in [https://github.com/fern-api/fern/pull/3071](https://github.com/fern-api/fern/pull/3071)\
* (fix, ruby): Ensure the name passed into the `X-Fern-SDK-Name` header is the name of the gem, not the client class by @armandobelardo in [https://github.com/fern-api/fern/pull/3073](https://github.com/fern-api/fern/pull/3073)\
* (fix, typescript): sdk code snippets dont render empty dicts for parameters with default values by @dsinghvi in [https://github.com/fern-api/fern/pull/3074](https://github.com/fern-api/fern/pull/3074)\
* (chore): Refactor Pagination IR to support offset by @amckinney in [https://github.com/fern-api/fern/pull/3072](https://github.com/fern-api/fern/pull/3072)\
* (chore, internal): move `docs-config` to use local typescript sdk gen by @abvthecity in [https://github.com/fern-api/fern/pull/3047](https://github.com/fern-api/fern/pull/3047)\
* (feature, beta): support reading `changelog` dir from api directory by @dsinghvi in [https://github.com/fern-api/fern/pull/3075](https://github.com/fern-api/fern/pull/3075)\
* (fix, express): make express generator respect it's version while publishing by @armandobelardo in [https://github.com/fern-api/fern/pull/3084](https://github.com/fern-api/fern/pull/3084)\
* (fix): address recursive loop in example gen with a max depth and lookback by @armandobelardo in [https://github.com/fern-api/fern/pull/3086](https://github.com/fern-api/fern/pull/3086)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.0-rc3...0.18.5](https://github.com/fern-api/fern/compare/0.19.0-rc3...0.18.5)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.0-rc4...0.19.0-rc5](https://github.com/fern-api/fern/compare/0.19.0-rc4...0.19.0-rc5)\
\
## New Contributors\
\
* @mscolnick made their first contribution in [https://github.com/fern-api/fern/pull/3104](https://github.com/fern-api/fern/pull/3104)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.19.0-rc5...0.19.0-rc6](https://github.com/fern-api/fern/compare/0.19.0-rc5...0.19.0-rc6)\
\
\
# February 27, 2024\
\
## 0.18.5\
\
**`(chore):`** ## What's Changed\
\
* (chore, go): Release fern-go-sdk 0.17.0 by @amckinney in [https://github.com/fern-api/fern/pull/3066](https://github.com/fern-api/fern/pull/3066)\
* (feature, go): supports multiple files in upload by @amckinney in [https://github.com/fern-api/fern/pull/3070](https://github.com/fern-api/fern/pull/3070)\
* (feature, ts): deep object query parameter serialization  by @dsinghvi in [https://github.com/fern-api/fern/pull/3060](https://github.com/fern-api/fern/pull/3060)\
* (chore): CLI supports providing IR v33 to TypeScript generators  by @dsinghvi in [https://github.com/fern-api/fern/pull/3060](https://github.com/fern-api/fern/pull/3060)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.18.4...0.18.5](https://github.com/fern-api/fern/compare/0.18.4...0.18.5)\
\
\
# February 26, 2024\
\
## 0.18.3\
\
**`(chore):`** ## What's Changed\
\
* (fix, java): leverage callTimeout instead of readTimeout for RequestOptions timeout configuration by @armandobelardo in [https://github.com/fern-api/fern/pull/3031](https://github.com/fern-api/fern/pull/3031)\
* (fix, java): Address NPE for RequestOptions with new timeout feature by @armandobelardo in [https://github.com/fern-api/fern/pull/3053](https://github.com/fern-api/fern/pull/3053)\
* (fix, go): Snippets for optional primitive aliases are accurate by @amckinney in [https://github.com/fern-api/fern/pull/3050](https://github.com/fern-api/fern/pull/3050)\
* (fix, python): move from lists to sequences when using lists in function signatures by @armandobelardo in [https://github.com/fern-api/fern/pull/3040](https://github.com/fern-api/fern/pull/3040)\
* (fix, java) Use safe name to generate discriminator wrapper class by @kikones34 in [https://github.com/fern-api/fern/pull/2961](https://github.com/fern-api/fern/pull/2961)\
* (fix, python): just use jsonable\\_encoder and remove .value from enum references by @armandobelardo in [https://github.com/fern-api/fern/pull/3044](https://github.com/fern-api/fern/pull/3044)\
* (fix, python): fix envvars scanning by updating the ApiError usage by @armandobelardo in [https://github.com/fern-api/fern/pull/3046](https://github.com/fern-api/fern/pull/3046)\
* (feature): OpenAPI importer attempts to use tag order to render endpoints if possible by @dsinghvi in [https://github.com/fern-##](https://github.com/fern-##)\
* (improvement, python): make optional fields not required by default by @armandobelardo in [https://github.com/fern-api/fern/pull/3041](https://github.com/fern-api/fern/pull/3041)\
* (feature): Add pagination (IRv35) by @amckinney in [https://github.com/fern-api/fern/pull/2985](https://github.com/fern-api/fern/pull/2985)\
* (feature): support asyncapi examples via `x-fern-examples` by @dsinghvi in [https://github.com/fern-api/fern/pull/3042](https://github.com/fern-api/fern/pull/3042)\
* (feature): generate default examples for WebSocket Sessions by @dsinghvi in [https://github.com/fern-api/fern/pull/3039](https://github.com/fern-api/fern/pull/3039)\
* (fix): fern check no longer throws when an undiscriminated union is a list of primitives by @dsinghvi in [https://github.com/fern-api/fern/pull/3055](https://github.com/fern-api/fern/pull/3055)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.18.2...0.18.3-rc0](https://github.com/fern-api/fern/compare/0.18.2...0.18.3-rc0)\
\
## New Contributors\
\
* @kikones34 made their first contribution in [https://github.com/fern-api/fern/pull/2961](https://github.com/fern-api/fern/pull/2961)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.18.3-rc1...0.18.3-rc2](https://github.com/fern-api/fern/compare/0.18.3-rc1...0.18.3-rc2)\
\
\
# February 22, 2024\
\
## 0.18.2\
\
**`(chore):`** ## What's Changed\
\
* (feature, python): introduce feature flag to simplify imports in python and remove the nested `resources` directory by @dsinghvi in [https://github.com/fern-api/fern/pull/3029](https://github.com/fern-api/fern/pull/3029)\
* (chore, internal): move `openapi-ir` to use local typescript sdk codegen by @dsinghvi in [https://github.com/fern-api/fern/pull/3033](https://github.com/fern-api/fern/pull/3033)\
* (docs): external sidebar links, filled navbar button, tab slug overrides by @abvthecity in [https://github.com/fern-api/fern/pull/3034](https://github.com/fern-api/fern/pull/3034)\
* (feature): Add Go snippet generation by @amckinney in [https://github.com/fern-api/fern/pull/3035](https://github.com/fern-api/fern/pull/3035)\
* (feature): Importer brings in Websocket Channels from `AsyncAPI`  by @dsinghvi in [https://github.com/fern-api/fern/pull/3037](https://github.com/fern-api/fern/pull/3037)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.18.1...0.18.2](https://github.com/fern-api/fern/compare/0.18.1...0.18.2)\
\
\
# February 21, 2024\
\
## 0.18.1\
\
**`(chore):`** ## What's Changed\
\
* docs: define fern as a toolkit by @dannysheridan in [https://github.com/fern-api/fern/pull/2974](https://github.com/fern-api/fern/pull/2974)\
* (feature): introduce websocket channel into fern definition by @dsinghvi in [https://github.com/fern-api/fern/pull/2975](https://github.com/fern-api/fern/pull/2975)\
* (fix): `fern write-overrides` uses summary to generate method name if no operation id and tag are present by @dsinghvi in [https://github.com/fern-api/fern/pull/2976](https://github.com/fern-api/fern/pull/2976)\
* (python, feat): add in request options to python by @armandobelardo in [https://github.com/fern-api/fern/pull/2926](https://github.com/fern-api/fern/pull/2926)\
* (fix):  postman collection is published appropriately by @dsinghvi in [https://github.com/fern-api/fern/pull/2978](https://github.com/fern-api/fern/pull/2978)\
* (internal): add websocket to IR by @dsinghvi in [https://github.com/fern-api/fern/pull/2981](https://github.com/fern-api/fern/pull/2981)\
* (internal): register websocket schemas with fdr by @dsinghvi in [https://github.com/fern-api/fern/pull/2983](https://github.com/fern-api/fern/pull/2983)\
* python, fix: revert regressions in writing circular references by @armandobelardo in [https://github.com/fern-api/fern/pull/2988](https://github.com/fern-api/fern/pull/2988)\
* (typescript): always use `node-fetch` when in Node.js by @dsinghvi in [https://github.com/fern-api/fern/pull/2989](https://github.com/fern-api/fern/pull/2989)\
* (typescript): Fetcher supports sending bytes in request body in `0.11.4` by @dsinghvi in [https://github.com/fern-api/fern/pull/2991](https://github.com/fern-api/fern/pull/2991)\
* (feature): make sure casing overrides take affect by @dsinghvi in [https://github.com/fern-api/fern/pull/2992](https://github.com/fern-api/fern/pull/2992)\
* (fix): IR generation respects casing overrides by @dsinghvi in [https://github.com/fern-api/fern/pull/2994](https://github.com/fern-api/fern/pull/2994)\
* chore, ruby: release the ruby generators to include IR compatibility fix by @armandobelardo in [https://github.com/fern-api/fern/pull/2995](https://github.com/fern-api/fern/pull/2995)\
* (fix): `x-fern-webhook` respects sdk method and group name by @dsinghvi in [https://github.com/fern-api/fern/pull/2996](https://github.com/fern-api/fern/pull/2996)\
* (feat, openapi): add global header aliasing by @armandobelardo in [https://github.com/fern-api/fern/pull/2990](https://github.com/fern-api/fern/pull/2990)\
* feat, ts: add in a reference generator class by @armandobelardo in [https://github.com/fern-api/fern/pull/2998](https://github.com/fern-api/fern/pull/2998)\
* improvement: tweaks to how we write references by @armandobelardo in [https://github.com/fern-api/fern/pull/3001](https://github.com/fern-api/fern/pull/3001)\
* (feat, java): add timeout to request options by @armandobelardo in [https://github.com/fern-api/fern/pull/2973](https://github.com/fern-api/fern/pull/2973)\
* chore: nest Go changelog within ./go/sdk by @dannysheridan in [https://github.com/fern-api/fern/pull/3004](https://github.com/fern-api/fern/pull/3004)\
* docs: delete unused pages by @minaelee in [https://github.com/fern-api/fern/pull/3008](https://github.com/fern-api/fern/pull/3008)\
* docs: fix broken link  by @minaelee in [https://github.com/fern-api/fern/pull/3007](https://github.com/fern-api/fern/pull/3007)\
* (chore, internal): speed up seed tests by using custom runner by @dsinghvi in [https://github.com/fern-api/fern/pull/3005](https://github.com/fern-api/fern/pull/3005)\
* (chore, internal): introduce telemetry for seed CLI by @dsinghvi in [https://github.com/fern-api/fern/pull/3009](https://github.com/fern-api/fern/pull/3009)\
* (fix): optional enum body parameters now pass check by @dsinghvi in [https://github.com/fern-api/fern/pull/2914](https://github.com/fern-api/fern/pull/2914)\
* (fix, python): literals are properly accepted as `query`, `path`, `header`, inlined body and referenced body parameters by @dsinghvi in [https://github.com/fern-api/fern/pull/3012](https://github.com/fern-api/fern/pull/3012)\
* improvement: allow files to be arrays within the IR by @armandobelardo in [https://github.com/fern-api/fern/pull/2993](https://github.com/fern-api/fern/pull/2993)\
* (fix, typescript): core.Stream is browser compatible by @dsinghvi in [https://github.com/fern-api/fern/pull/3017](https://github.com/fern-api/fern/pull/3017)\
* (chore, internal): setup browser playground for ts generator by @dsinghvi in [https://github.com/fern-api/fern/pull/3019](https://github.com/fern-api/fern/pull/3019)\
* build(deps): bump golang.org/x/tools from 0.17.0 to 0.18.0 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3015](https://github.com/fern-api/fern/pull/3015)\
* (typescript, release): release browser compatible streaming in `0.11.5` by @dsinghvi in [https://github.com/fern-api/fern/pull/3022](https://github.com/fern-api/fern/pull/3022)\
* (internal) rename Websocket to WebSocket and bump fdr by @abvthecity in [https://github.com/fern-api/fern/pull/3018](https://github.com/fern-api/fern/pull/3018)\
* feats, ruby: add in idempotency headers and improve enum and union implementations by @armandobelardo in [https://github.com/fern-api/fern/pull/3020](https://github.com/fern-api/fern/pull/3020)\
* improvement, python: update python file type to be more reflective or HTTPX types and allow lists of files by @armandobelardo in [https://github.com/fern-api/fern/pull/3010](https://github.com/fern-api/fern/pull/3010)\
* build(deps): bump axios from 0.27.2 to 0.28.0 by @dependabot in [https://github.com/fern-api/fern/pull/3024](https://github.com/fern-api/fern/pull/3024)\
* fix: websocket inline jsonExample and ir-to-fdr path by @abvthecity in [https://github.com/fern-api/fern/pull/3026](https://github.com/fern-api/fern/pull/3026)\
* improvement, seed: reduce size of seed containers and speed up python and java tests by @armandobelardo in [https://github.com/fern-api/fern/pull/3011](https://github.com/fern-api/fern/pull/3011)\
* feature, python: allow for users to define custom exports from **init**.py by @armandobelardo in [https://github.com/fern-api/fern/pull/3025](https://github.com/fern-api/fern/pull/3025)\
* build(deps): bump github.com/fern-api/generator-exec-go from 0.0.574 to 0.0.600 in /generators/go by @dependabot in [https://github.com/fern-api/fern/pull/3021](https://github.com/fern-api/fern/pull/3021)\
* (java, fix): file upload endpoints compile when determining mime type by @dsinghvi in [https://github.com/fern-api/fern/pull/3027](https://github.com/fern-api/fern/pull/3027)\
* (fix): a single enum with x-fern-enum is not turned into a literal by @dsinghvi in [https://github.com/fern-api/fern/pull/3028](https://github.com/fern-api/fern/pull/3028)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.18.0...0.18.1](https://github.com/fern-api/fern/compare/0.18.0...0.18.1)\
\
\
# February 16, 2024\
\
## 0.18.1-rc2\
\
**`(chore):`** ## What's Changed\
\
* (chore, ruby): release the ruby generators to include IR compatibility fix by @armandobelardo in [https://github.com/fern-api/fern/pull/2995](https://github.com/fern-api/fern/pull/2995)\
* (cli, fix): `x-fern-webhook` respects sdk method and group name by @dsinghvi in [https://github.com/fern-api/fern/pull/2996](https://github.com/fern-api/fern/pull/2996)\
* (cli, feature): IR generation respects casing overrides by @dsinghvi in [https://github.com/fern-api/fern/pull/2994](https://github.com/fern-api/fern/pull/2994)\
* (python, feat): add in request options to python by @armandobelardo in [https://github.com/fern-api/fern/pull/2926](https://github.com/fern-api/fern/pull/2926)\
* (typescript): always use `node-fetch` when in Node.js by @dsinghvi in [https://github.com/fern-api/fern/pull/2989](https://github.com/fern-api/fern/pull/2989)\
* (typescript): Fetcher supports sending bytes in request body in `0.11.4` by @dsinghvi in [https://github.com/fern-api/fern/pull/2991](https://github.com/fern-api/fern/pull/2991)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.18.0...0.18.0-rc0](https://github.com/fern-api/fern/compare/0.18.0...0.18.0-rc0)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.18.1-rc1...0.18.1-rc2](https://github.com/fern-api/fern/compare/0.18.1-rc1...0.18.1-rc2)\
\
\
# February 14, 2024\
\
## 0.18.0\
\
**`(chore):`** ## What's Changed\
\
* (fix): handle `optional` multipart file upload parameters by @armandobelardo in [https://github.com/fern-api/fern/pull/2964](https://github.com/fern-api/fern/pull/2964)\
* (break): sever base paths are no longer pre-pended to endpoint URLs in OpenAPI Parser by @dsinghvi in [https://github.com/fern-api/fern/pull/2972](https://github.com/fern-api/fern/pull/2972)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.17.10...0.18.0](https://github.com/fern-api/fern/compare/0.17.10...0.18.0)\
\
\
# February 13, 2024\
\
## 0.17.9\
\
**`(chore):`** ## What's Changed\
\
* (internal): initialize csharp AST by @dsinghvi in [https://github.com/fern-api/fern/pull/2938](https://github.com/fern-api/fern/pull/2938)\
* (feature): go generator supports whitelabelling by @dsinghvi in [https://github.com/fern-api/fern/pull/2953](https://github.com/fern-api/fern/pull/2953)\
* (feature): OpenAPI importer handles extending undiscriminated unions if they are objects by @dsinghvi in [https://github.com/fern-api/fern/pull/2956](https://github.com/fern-api/fern/pull/2956)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.17.8...0.17.9](https://github.com/fern-api/fern/compare/0.17.8...0.17.9)\
\
\
# February 11, 2024\
\
## 0.17.8\
\
**`(chore):`** ## What's Changed\
\
* (feature): support whitelabeling SDKs  by @dsinghvi in [https://github.com/fern-api/fern/pull/2928](https://github.com/fern-api/fern/pull/2928)\
* (feature): css + js + measure img size by @abvthecity in [https://github.com/fern-api/fern/pull/2872api/fern/pull/2937](https://github.com/fern-api/fern/pull/2872api/fern/pull/2937)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.17.7...0.17.8](https://github.com/fern-api/fern/compare/0.17.7...0.17.8)\
\
\
# February 9, 2024\
\
## 0.17.3\
\
**`(chore):`** ## What's Changed\
\
* improvement: add better numbering support for snakecasing when smartCasing is enabled by @armandobelardo in [https://github.com/fern-api/fern/pull/2921](https://github.com/fern-api/fern/pull/2921)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.17.1...0.17.3](https://github.com/fern-api/fern/compare/0.17.1...0.17.3)\
\
\
# February 8, 2024\
\
## 0.17.2\
\
**`(chore):`** ## What's Changed\
\
* (fix): misc improvements to OpenAPI example generation by @dsinghvi in [https://github.com/fern-api/fern/pull/2916](https://github.com/fern-api/fern/pull/2916)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.17.1...0.17.2](https://github.com/fern-api/fern/compare/0.17.1...0.17.2)\
\
\
# February 7, 2024\
\
## 0.17.0\
\
**`(chore):`** - **break**: The OpenAPI importer now considers the `title` field when generating a schema name. It only considers this field if there is no whitespace and only contains alphabetic characters. We're constantly trying to improve Fern to generate as idiomatic code as possible and naming schemas correctly is a huge part of that.\
\
By upgrading the Fern CLI to a `0.17.x` version, any SDKs with the following OpenAPI would receive compile breaks b/c the object would be renamed as `Bar`.\
\
```yaml\
Foo: \
  title: Bar\
  type: object\
```\
\
\
# February 6, 2024\
\
## 0.16.44-rc1\
\
**`(chore):`** ## What's Changed\
\
* (feature): additional layout options for docs by @abvthecity in [https://github.com/fern-api/fern/pull/2781](https://github.com/fern-api/fern/pull/2781)\
* (feature): `x-fern-examples` extension in OpenAPI operation by @abvthecity in [https://github.com/fern-api/fern/pull/2856](https://github.com/fern-api/fern/pull/2856)\
  **Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.43...0.16.44-rc0](https://github.com/fern-api/fern/compare/0.16.43...0.16.44-rc0)\
* (java): java sdk, model and spring generators now support boolean literals by @dsinghvi in [https://github.com/fern-api/fern/pull/2887](https://github.com/fern-api/fern/pull/2887)\
* fixes: \uc0\u55357 \u56462  Ruby: Fix typos, imports and several other papercuts within SDK generation by @armandobelardo in [https://github.com/fern-api/fern/pull/2868](https://github.com/fern-api/fern/pull/2868)\
* fix: Ruby: fix version header and file write location by @armandobelardo in [https://github.com/fern-api/fern/pull/2889](https://github.com/fern-api/fern/pull/2889)\
* fix: ruby: support deeply nested objects correctly by @armandobelardo in [https://github.com/fern-api/fern/pull/2895](https://github.com/fern-api/fern/pull/2895)\
* chore: allow releasing RCs through Actions by @armandobelardo in [https://github.com/fern-api/fern/pull/2896](https://github.com/fern-api/fern/pull/2896)\
* fix: update the dev release workflow to leverage full commit history by @armandobelardo in [https://github.com/fern-api/fern/pull/2897](https://github.com/fern-api/fern/pull/2897)\
* additional config options by @abvthecity in [https://github.com/fern-api/fern/pull/2781](https://github.com/fern-api/fern/pull/2781)\
* improvement: update readme to expose fastapi configs by @armandobelardo in [https://github.com/fern-api/fern/pull/2901](https://github.com/fern-api/fern/pull/2901)\
* fix: ruby: address potential naming conflicts within SDK by @armandobelardo in [https://github.com/fern-api/fern/pull/2902](https://github.com/fern-api/fern/pull/2902)\
* fix: Ruby: ensure services always have a name by @armandobelardo in [https://github.com/fern-api/fern/pull/2903](https://github.com/fern-api/fern/pull/2903)\
* fix: improve handling color config for dark vs light themes by @abvthecity in [https://github.com/fern-api/fern/pull/2904](https://github.com/fern-api/fern/pull/2904)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.43...0.16.44-rc1](https://github.com/fern-api/fern/compare/0.16.43...0.16.44-rc1)\
\
\
# February 4, 2024\
\
## 0.16.43\
\
**`(chore):`** ## What's Changed\
\
* (ruby): 0.0.1 Release by @armandobelardo in [https://github.com/fern-api/fern/pull/2858](https://github.com/fern-api/fern/pull/2858)\
* (java): java sdk generator supports idempotency headers by @dsinghvi in [https://github.com/fern-api/fern/pull/2884](https://github.com/fern-api/fern/pull/2884)\
* (cli): `x-fern-streaming` respects extensions on stream property by @dsinghvi in [https://github.com/fern-api/fern/pull/2853](https://github.com/fern-api/fern/pull/2853)\
* (cli): list overrides win over OpenAPI and do not get combined by @dsinghvi in [https://github.com/fern-api/fern/pull/2854](https://github.com/fern-api/fern/pull/2854)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.43-rc0...0.16.43-rc1](https://github.com/fern-api/fern/compare/0.16.43-rc0...0.16.43-rc1)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.43-rc1...0.16.43-rc2](https://github.com/fern-api/fern/compare/0.16.43-rc1...0.16.43-rc2)\
\
\
# February 1, 2024\
\
## 0.16.42\
\
**`(chore):`** ## What's Changed\
\
* improvement: TypeScript SDK steps in quickstart by @dannysheridan in [https://github.com/fern-api/fern/pull/2829](https://github.com/fern-api/fern/pull/2829)\
* fix: increase python generator recursion depth to allow for deeply nested examples by @armandobelardo  in [https://github.com/fern-api/fern/pull/2825](https://github.com/fern-api/fern/pull/2825)\
* fix: OpenAPI importer respects `x-examples` key by @dsinghvi in [https://github.com/fern-api/fern/pull/2845](https://github.com/fern-api/fern/pull/2845)\
* (fix): Add support for custom code samples by @abvthecity in [https://github.com/fern-api/fern/pull/2842](https://github.com/fern-api/fern/pull/2842)\
* (fix): OpenAPI importer brings in example names by @dsinghvi in [https://github.com/fern-api/fern/pull/2847](https://github.com/fern-api/fern/pull/2847)\
* (fix): `fern write-definition` does not remove markdown formatting by @dsinghvi in [https://github.com/fern-api/fern/pull/2849](https://github.com/fern-api/fern/pull/2849)\
* (feature): introduce `x-fern-resolutions` extension by @dsinghvi in [https://github.com/fern-api/fern/pull/2844](https://github.com/fern-api/fern/pull/2844)\
\
## New Contributors\
\
* @abvthecity made their first contribution in [https://github.com/fern-api/fern/pull/2842](https://github.com/fern-api/fern/pull/2842)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.41...0.16.42](https://github.com/fern-api/fern/compare/0.16.41...0.16.42)\
\
\
# January 29, 2024\
\
## 0.16.40\
\
**`(chore):`** ## What's Changed\
\
* (fix): add a `disable-example` flag for generators by @dsinghvi in [https://github.com/fern-api/fern/pull/2826](https://github.com/fern-api/fern/pull/2826)\
  ```yaml\
  generators: \
    - name: ...\
       version: ...\
       disable-examples: true # A temporary workaround while we iron out example deserialization bugs in python\
  ```\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.39...0.16.40](https://github.com/fern-api/fern/compare/0.16.39...0.16.40)\
\
\
# January 26, 2024\
\
## 0.16.38\
\
**`(chore):`** ## What's Changed\
\
* (fix): OpenAPI importer uses the `value` field when looking at `examples` by @dsinghvi in [https://github.com/fern-api/fern/pull/2803](https://github.com/fern-api/fern/pull/2803)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.37...0.16.38](https://github.com/fern-api/fern/compare/0.16.37...0.16.38)\
\
\
# January 25, 2024\
\
## 0.16.37\
\
**`(chore):`** ## What's Changed\
\
* (fix): Allow Ruby generator to work on IRv32 by @armandobelardo in [https://github.com/fern-api/fern/pull/2668](https://github.com/fern-api/fern/pull/2668)\
* (chore): Go generators use IRv32 by @amckinney in [https://github.com/fern-api/fern/pull/2672](https://github.com/fern-api/fern/pull/2672)\
* (fix): python sdk sends enum value for inlined requests by @dsinghvi in [https://github.com/fern-api/fern/pull/2793](https://github.com/fern-api/fern/pull/2793)\
* (release): 0.8.0 of python-sdk generator by @dsinghvi in [https://github.com/fern-api/fern/pull/2795](https://github.com/fern-api/fern/pull/2795)\
* (fix): OpenAPI importer query parameters always generate valid names by @dsinghvi in [https://github.com/fern-api/fern/pull/2801](https://github.com/fern-api/fern/pull/2801)\
* (fix): OpenAPI importer example generation skips object query params by @dsinghvi in [https://github.com/fern-api/fern/pull/2800](https://github.com/fern-api/fern/pull/2800)\
\
## New Contributors\
\
* @SK-Sam made their first contribution in [https://github.com/fern-api/fern/pull/2687](https://github.com/fern-api/fern/pull/2687)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.36...0.16.37](https://github.com/fern-api/fern/compare/0.16.36...0.16.37)\
\
\
# January 19, 2024\
\
## 0.16.36\
\
**`(chore):`** ## What's Changed\
\
* feature: CLI supports running Ruby sdk + model generator by @armandobelardo in [https://github.com/fern-api/fern/pull/2570](https://github.com/fern-api/fern/pull/2570)\
* fix: OpenAPI importer adds variables accordingly by @dsinghvi in [https://github.com/fern-api/fern/pull/2667](https://github.com/fern-api/fern/pull/2667)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.35...0.16.36](https://github.com/fern-api/fern/compare/0.16.35...0.16.36)\
\
\
# January 18, 2024\
\
## 0.16.35\
\
**`(chore):`** ## What's Changed\
\
* fix: OpenAPI importer supports union examples  by @dsinghvi in [https://github.com/fern-api/fern/pull/2653](https://github.com/fern-api/fern/pull/2653)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.34...0.16.35](https://github.com/fern-api/fern/compare/0.16.34...0.16.35)\
\
\
# January 17, 2024\
\
## 0.16.34\
\
**`(chore):`** ## What's Changed\
\
* fix: OpenAPI importer supports generating examples for `unknown` by @dsinghvi in [https://github.com/fern-api/fern/pull/2624](https://github.com/fern-api/fern/pull/2624)\
* fix: auto generation of primitive examples by @dsinghvi in [https://github.com/fern-api/fern/pull/2625](https://github.com/fern-api/fern/pull/2625)\
* fix: misc fixes to OpenAPI example generation by @dsinghvi in [https://github.com/fern-api/fern/pull/2630](https://github.com/fern-api/fern/pull/2630)\
* fix: `getAllProperties` visits references by @dsinghvi in [https://github.com/fern-api/fern/pull/2631](https://github.com/fern-api/fern/pull/2631)\
* fix: OpenAPI importer uses generated names for aliases by @dsinghvi in [https://github.com/fern-api/fern/pull/2632](https://github.com/fern-api/fern/pull/2632)\
* fix: inlined component schemas are added to **package**.yml by @dsinghvi in [https://github.com/fern-api/fern/pull/2633](https://github.com/fern-api/fern/pull/2633)\
* fix: OpenAPI importer handles property conflicts from grandparents by @dsinghvi in [https://github.com/fern-api/fern/pull/2637](https://github.com/fern-api/fern/pull/2637)\
* fix: OpenAPI importer replaces schemas that start with numbers with alphabetic notation by @dsinghvi in [https://github.com/fern-api/fern/pull/2638](https://github.com/fern-api/fern/pull/2638)\
* fix: upgrade fiddle sdk to `0.0.386` so that license generation works by @dsinghvi in [https://github.com/fern-api/fern/pull/2643](https://github.com/fern-api/fern/pull/2643)\
* fix: OpenAPI importer removes redundant path from environment by @dsinghvi in [https://github.com/fern-api/fern/pull/2650](https://github.com/fern-api/fern/pull/2650)\
* fix: OpenAPI importer doesn't extend aliased schemas that have a property conflict by @dsinghvi in [https://github.com/fern-api/fern/pull/2651](https://github.com/fern-api/fern/pull/2651)\
* fix: OpenAPI importer doesn't set name override for nested key value pair by @dsinghvi in [https://github.com/fern-api/fern/pull/2652](https://github.com/fern-api/fern/pull/2652)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.33...0.16.34](https://github.com/fern-api/fern/compare/0.16.33...0.16.34)\
\
\
# January 15, 2024\
\
## 0.16.33\
\
**`(chore):`** ## What's Changed\
\
* feature: add `fern mock` command by @amckinney in [https://github.com/fern-api/fern/pull/2618](https://github.com/fern-api/fern/pull/2618)\
* feature: OpenAPI importer looks at `examples` property by @dsinghvi in [https://github.com/fern-api/fern/pull/2621](https://github.com/fern-api/fern/pull/2621)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.32...0.16.33](https://github.com/fern-api/fern/compare/0.16.32...0.16.33)\
\
\
# January 13, 2024\
\
## 0.16.32\
\
**`(chore):`** ## What's Changed\
\
* fix: OpenAPI importer handles converting boolean enums  @dsinghvi in [https://github.com/fern-api/fern/pull/2616](https://github.com/fern-api/fern/pull/2616)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.31...0.16.32](https://github.com/fern-api/fern/compare/0.16.31...0.16.32)\
\
\
# January 12, 2024\
\
## 0.16.29\
\
**`(chore):`** ## What's Changed\
\
* fix: OpenAPI importer supports reading `x-fern-sdk-return-value` by @dsinghvi in [https://github.com/fern-api/fern/pull/2610](https://github.com/fern-api/fern/pull/2610)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.28...0.16.29](https://github.com/fern-api/fern/compare/0.16.28...0.16.29)\
\
\
# January 11, 2024\
\
## 0.16.27\
\
**`(chore):`** ## What's Changed\
\
* test: Add test for file upload with query params by @amckinney in [https://github.com/fern-api/fern/pull/2441](https://github.com/fern-api/fern/pull/2441)\
* test: Replace /bin/bash with /bin/sh by @amckinney in [https://github.com/fern-api/fern/pull/2595](https://github.com/fern-api/fern/pull/2595)\
* docs: update quickstart.mdx by @minaelee in [https://github.com/fern-api/fern/pull/2596](https://github.com/fern-api/fern/pull/2596)\
* fix: send descriptions for union base properties when generating docs by @dsinghvi in [https://github.com/fern-api/fern/pull/2601](https://github.com/fern-api/fern/pull/2601)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.25...0.16.26](https://github.com/fern-api/fern/compare/0.16.25...0.16.26)\
\
\
# January 10, 2024\
\
## 0.16.24\
\
**`(chore):`** ## What's Changed\
\
* fix: OpenAPI converter uses literals when anyOf has inlined enums  by @dsinghvi in [https://github.com/fern-api/fern/pull/2589](https://github.com/fern-api/fern/pull/2589)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.23...0.16.24](https://github.com/fern-api/fern/compare/0.16.23...0.16.24)\
\
\
# January 9, 2024\
\
## 0.16.23\
\
**`(chore):`** ## What's Changed\
\
* fix: make `generators.yml` optional if no generators by @dsinghvi in [https://github.com/fern-api/fern/pull/2585](https://github.com/fern-api/fern/pull/2585)\
\
## New Contributors\
\
* @minaelee made their first contribution in [https://github.com/fern-api/fern/pull/2567](https://github.com/fern-api/fern/pull/2567)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.22...0.16.23](https://github.com/fern-api/fern/compare/0.16.22...0.16.23)\
\
\
# January 1, 2024\
\
## 0.16.21\
\
**`(chore):`** ## What's Changed\
\
* fix: OpenAPI importer handles null `anyOf` with more than 3 variants by @dsinghvi in [https://github.com/fern-api/fern/pull/2549](https://github.com/fern-api/fern/pull/2549)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.20...0.16.21](https://github.com/fern-api/fern/compare/0.16.20...0.16.21)\
\
\
# December 29, 2023\
\
## 0.16.20\
\
**`(chore):`** ## What's Changed\
\
* feature: `push` mode for GitHub repository by @dsinghvi in [https://github.com/fern-api/fern/pull/2546](https://github.com/fern-api/fern/pull/2546)\
  ```yaml\
  # generators.yml\
  - name: fernapi/fern-python-sdk\
    ...\
    github: \
      mode: push\
      repository: owner/repo\
      branch: # optional branch, if omitted uses the default channel \
  ```\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.19...0.16.20](https://github.com/fern-api/fern/compare/0.16.19...0.16.20)\
\
\
# December 23, 2023\
\
## 0.16.17\
\
**`(chore):`** ## What's Changed\
\
* feature: openapi importer generates oauth 2 scopes enum by @dsinghvi in [https://github.com/fern-api/fern/pull/2540](https://github.com/fern-api/fern/pull/2540)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.16...0.16.17](https://github.com/fern-api/fern/compare/0.16.16...0.16.17)\
\
\
# December 22, 2023\
\
## 0.16.14\
\
**`(chore):`** ## What's Changed\
\
* feature: `fern write-definition` writes out api dependencies by @dsinghvi in [https://github.com/fern-api/fern/pull/2531](https://github.com/fern-api/fern/pull/2531)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.13...0.16.14](https://github.com/fern-api/fern/compare/0.16.13...0.16.14)\
\
\
# December 21, 2023\
\
## 0.16.13\
\
**`(chore):`** ## What's Changed\
\
* feature: support property level audiences by @dsinghvi in [https://github.com/fern-api/fern/pull/2526](https://github.com/fern-api/fern/pull/2526)\
* feature: openapi importer supports importing property level audiences by @dsinghvi in [https://github.com/fern-api/fern/pull/2528](https://github.com/fern-api/fern/pull/2528)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.12...0.16.13](https://github.com/fern-api/fern/compare/0.16.12...0.16.13)\
\
\
# December 20, 2023\
\
## 0.16.12\
\
**`(chore):`** ## What's Changed\
\
* internal: seed accepts path to api directory for custom fixture by @dsinghvi in [https://github.com/fern-api/fern/pull/2516](https://github.com/fern-api/fern/pull/2516)\
* fix: fern python generators rely on ir v31 by @dsinghvi in [https://github.com/fern-api/fern/pull/2517](https://github.com/fern-api/fern/pull/2517)\
* feature: run prettier on doc strings by @dsinghvi in [https://github.com/fern-api/fern/pull/2508](https://github.com/fern-api/fern/pull/2508)\
* fix: use `JSON.stringify` when writing IR by @dsinghvi in [https://github.com/fern-api/fern/pull/2511](https://github.com/fern-api/fern/pull/2511)\
* fix: OpenAPI importer handles self referencing schemas  by @dsinghvi in [https://github.com/fern-api/fern/pull/2512](https://github.com/fern-api/fern/pull/2512)\
* fix: handle explicit `null` strings in OpenAPI schemas by @dsinghvi in [https://github.com/fern-api/fern/pull/2514](https://github.com/fern-api/fern/pull/2514)\
* fix: `ResourceList` in fhir is an undiscriminated union with literal properties by @armandobelardo in [https://github.com/fern-api/fern/pull/2513](https://github.com/fern-api/fern/pull/2513)\
* fix: add `int`, `float`, and `complex` to python reserved words by @armandobelardo in [https://github.com/fern-api/fern/pull/2523](https://github.com/fern-api/fern/pull/2523)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.11...0.16.12](https://github.com/fern-api/fern/compare/0.16.11...0.16.12)\
\
\
# December 18, 2023\
\
## 0.16.10\
\
**`(chore):`** ## What's Changed\
\
* document: x-fern-server-name extension by @dannysheridan in [https://github.com/fern-api/fern/pull/2504](https://github.com/fern-api/fern/pull/2504)\
* feature: add x-fern-parameter-name extension by @amckinney in [https://github.com/fern-api/fern/pull/2489](https://github.com/fern-api/fern/pull/2489)\
* chore: seed exits 1 if tests fail  by @dsinghvi in [https://github.com/fern-api/fern/pull/2505](https://github.com/fern-api/fern/pull/2505)\
* fix: x-fern-streaming can be used with x-fern-group-name by @amckinney in [https://github.com/fern-api/fern/pull/2488](https://github.com/fern-api/fern/pull/2488)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.9...0.16.10](https://github.com/fern-api/fern/compare/0.16.9...0.16.10)\
\
\
# December 17, 2023\
\
## 0.16.8\
\
**`(chore):`** ## What's Changed\
\
* chore: run ci on forked PRs for contributors by @dsinghvi in [https://github.com/fern-api/fern/pull/2494](https://github.com/fern-api/fern/pull/2494)\
* internal: seed only runs one container per script for all fixtures by @armandobelardo in [https://github.com/fern-api/fern/pull/2492](https://github.com/fern-api/fern/pull/2492)\
* fix: typo in docs starter example repo by @dannysheridan in [https://github.com/fern-api/fern/pull/2496](https://github.com/fern-api/fern/pull/2496)\
* fix: header on quickstart page by @dannysheridan in [https://github.com/fern-api/fern/pull/2497](https://github.com/fern-api/fern/pull/2497)\
* fix: `fern write-definition` doesn't throw on non-OpenAPI workspaces by @dsinghvi in [https://github.com/fern-api/fern/pull/2499](https://github.com/fern-api/fern/pull/2499)\
* fix: `fern check` logs `All checks passed` if no errors @dsinghvi in [https://github.com/fern-api/fern/pull/2499](https://github.com/fern-api/fern/pull/2499)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.7...0.16.8](https://github.com/fern-api/fern/compare/0.16.7...0.16.8)\
\
\
# December 14, 2023\
\
## 0.16.7\
\
**`(chore):`** ## What's Changed\
\
* fix: openapi importer correctly imports across nested fern definition files by @dsinghvi in [https://github.com/fern-api/fern/pull/2491](https://github.com/fern-api/fern/pull/2491)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.6...0.16.7](https://github.com/fern-api/fern/compare/0.16.6...0.16.7)\
\
\
# December 13, 2023\
\
## 0.16.4\
\
**`(chore):`** ## What's Changed\
\
* internal: enable typescript code snippets in fern docs by @dsinghvi in [https://github.com/fern-api/fern/pull/2473](https://github.com/fern-api/fern/pull/2473)\
* internal: `generators.yml` in public-api by @dsinghvi in [https://github.com/fern-api/fern/pull/2475](https://github.com/fern-api/fern/pull/2475)\
* document: API-wide global configs in api.yml by @dannysheridan in [https://github.com/fern-api/fern/pull/2478](https://github.com/fern-api/fern/pull/2478)\
* fix: escape OpenAPI string examples that star with `$` by @dsinghvi in [https://github.com/fern-api/fern/pull/2483](https://github.com/fern-api/fern/pull/2483)\
* fix: handle OpenAPI importer handles unions `type: [string, object]` by @dsinghvi in [https://github.com/fern-api/fern/pull/2483](https://github.com/fern-api/fern/pull/2483)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.3...0.16.4](https://github.com/fern-api/fern/compare/0.16.3...0.16.4)\
\
\
# December 11, 2023\
\
## 0.16.3\
\
**`(chore):`** ## What's Changed\
\
* improvement: openapi importer enum name generator for like `>`, `<` , `<=`, `>=` by @dsinghvi in [https://github.com/fern-api/fern/pull/2471](https://github.com/fern-api/fern/pull/2471)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.2...0.16.3](https://github.com/fern-api/fern/compare/0.16.2...0.16.3)\
\
\
# December 10, 2023\
\
## 0.16.2\
\
**`(chore):`** ## What's Changed\
\
* docs: show example of list by @dannysheridan in [https://github.com/fern-api/fern/pull/2464](https://github.com/fern-api/fern/pull/2464)\
* docs: improve cli descriptions by @dannysheridan in [https://github.com/fern-api/fern/pull/2466](https://github.com/fern-api/fern/pull/2466)\
* fix: openapi importer enum generation is valid @dsinghvi in [https://github.com/fern-api/fern/pull/2468](https://github.com/fern-api/fern/pull/2468)\
* fix: openapi importer request references generation is valid @dsinghvi in [https://github.com/fern-api/fern/pull/2468](https://github.com/fern-api/fern/pull/2468)\
* fix: introduce `fern openapi-ir` for debugging @dsinghvi in [https://github.com/fern-api/fern/pull/2468](https://github.com/fern-api/fern/pull/2468)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.16.1...0.16.2](https://github.com/fern-api/fern/compare/0.16.1...0.16.2)\
\
\
# December 8, 2023\
\
## 0.16.0\
\
**`(chore):`** ## What's Changed\
\
* docs: add docs quickstart by @dannysheridan in [https://github.com/fern-api/fern/pull/2456](https://github.com/fern-api/fern/pull/2456)\
* docs: fix callout spacing by @dannysheridan in [https://github.com/fern-api/fern/pull/2457](https://github.com/fern-api/fern/pull/2457)\
* docs: example provided for path parameter by @dannysheridan in [https://github.com/fern-api/fern/pull/2458](https://github.com/fern-api/fern/pull/2458)\
* *feature*: support `x-fern-sdk-group-name` on schemas by @dsinghvi in [https://github.com/fern-api/fern/pull/2459](https://github.com/fern-api/fern/pull/2459)\
  **NOTE** The OpenAPI importer was drastically modified, so be careful upgrading to `0.16.0` and report any issues!\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.18...0.16.0](https://github.com/fern-api/fern/compare/0.15.18...0.16.0)\
\
\
# December 7, 2023\
\
## 0.15.17\
\
**`(chore):`** ## What's Changed\
\
* feature: support overlaying extensions using `x-fern-overrides-filepath` by @dsinghvi in [https://github.com/fern-api/fern/pull/2452](https://github.com/fern-api/fern/pull/2452)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.16...0.15.17](https://github.com/fern-api/fern/compare/0.15.16...0.15.17)\
\
\
# December 6, 2023\
\
## 0.15.12\
\
**`(chore):`** ## What's Changed\
\
* internal: seed supports configurable ouptut mode by @dsinghvi in [https://github.com/fern-api/fern/pull/2430](https://github.com/fern-api/fern/pull/2430)\
* internal: add examples to literal-headers test definition by @amckinney in [https://github.com/fern-api/fern/pull/2437](https://github.com/fern-api/fern/pull/2437)\
* internal: seed fixtures are dynamic by @amckinney in [https://github.com/fern-api/fern/pull/2440](https://github.com/fern-api/fern/pull/2440)\
* documentation: broken links in quickstart by @dannysheridan in [https://github.com/fern-api/fern/pull/2444](https://github.com/fern-api/fern/pull/2444)\
* feature: use tag order to set `navigation` in fern definition by @dsinghvi in [https://github.com/fern-api/fern/pull/2445](https://github.com/fern-api/fern/pull/2445)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.11...0.15.12](https://github.com/fern-api/fern/compare/0.15.11...0.15.12)\
\
\
# December 4, 2023\
\
## 0.15.11\
\
**`(chore):`** ## What's Changed\
\
* feature: use terminal link to render clickable docs URL by @dannysheridan in [https://github.com/fern-api/fern/pull/2391](https://github.com/fern-api/fern/pull/2391)\
* docs: Explain how SDKs and Docs use audiences by @dannysheridan in [https://github.com/fern-api/fern/pull/2411](https://github.com/fern-api/fern/pull/2411)\
* feature: send property level availability information to docs by @dsinghvi in [https://github.com/fern-api/fern/pull/2420](https://github.com/fern-api/fern/pull/2420)\
* feature: support undiscriminated union examples in ir by @dsinghvi in [https://github.com/fern-api/fern/pull/2425](https://github.com/fern-api/fern/pull/2425)\
* feature: support x-fern-ignore at the schema level by @dsinghvi in [https://github.com/fern-api/fern/pull/2428](https://github.com/fern-api/fern/pull/2428)\
* fix: correctly validate referenced examples that are being imported by @dsinghvi in [https://github.com/fern-api/fern/pull/2429](https://github.com/fern-api/fern/pull/2429)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.10...0.15.11](https://github.com/fern-api/fern/compare/0.15.10...0.15.11)\
\
\
# November 30, 2023\
\
## 0.15.7\
\
**`(chore):`** ## What's Changed\
\
* fix: compress fhir definition by having types extend `BaseResource`  by @dsinghvi in [https://github.com/fern-api/fern/pull/2387](https://github.com/fern-api/fern/pull/2387)\
* docs: availability in Fern Definition by @dannysheridan in [https://github.com/fern-api/fern/pull/2395](https://github.com/fern-api/fern/pull/2395)\
* fix: OpenAPI importer generates non-conflicting names for multipart file upload endpoints by @dsinghvi in [https://github.com/fern-api/fern/pull/2399](https://github.com/fern-api/fern/pull/2399)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.6...0.15.7](https://github.com/fern-api/fern/compare/0.15.6...0.15.7)\
\
\
# November 28, 2023\
\
## 0.15.6\
\
**`(chore):`** ## What's Changed\
\
* docs: how to control display order of your API reference by @dsinghvi in [https://github.com/fern-api/fern/pull/2366](https://github.com/fern-api/fern/pull/2366)\
* docs: .NET server code generator for C# by @dannysheridan in [https://github.com/fern-api/fern/pull/2354](https://github.com/fern-api/fern/pull/2354)\
* docs: improve fern's readme.md by @dannysheridan in [https://github.com/fern-api/fern/pull/2370](https://github.com/fern-api/fern/pull/2370)\
* docs: improve images in readme by @dannysheridan in [https://github.com/fern-api/fern/pull/2371](https://github.com/fern-api/fern/pull/2371)\
* docs: improve readme image by @dannysheridan in [https://github.com/fern-api/fern/pull/2372](https://github.com/fern-api/fern/pull/2372)\
* docs: add getting started to readme by @dannysheridan in [https://github.com/fern-api/fern/pull/2380](https://github.com/fern-api/fern/pull/2380)\
* docs: update bug-report.md by @dannysheridan in [https://github.com/fern-api/fern/pull/2375](https://github.com/fern-api/fern/pull/2375)\
* docs: file structure upon fern init by @dannysheridan in [https://github.com/fern-api/fern/pull/2381](https://github.com/fern-api/fern/pull/2381)\
* fix: fern no longer fails to parse nested maps (`map<string, map<string, int>>`)by @mmolash in [https://github.com/fern-api/fern/pull/2369](https://github.com/fern-api/fern/pull/2369)\
\
## New Contributors\
\
* @mmolash made their first contribution in [https://github.com/fern-api/fern/pull/2369](https://github.com/fern-api/fern/pull/2369)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.5...0.15.6](https://github.com/fern-api/fern/compare/0.15.5...0.15.6)\
\
\
# November 27, 2023\
\
## 0.15.4\
\
**`(chore):`** ## What's Changed\
\
* chore: use correct URL for preview server by @dsinghvi in [https://github.com/fern-api/fern/pull/2322](https://github.com/fern-api/fern/pull/2322)\
* fix: docs preview server no longer has cors requirement by @dsinghvi in [https://github.com/fern-api/fern/pull/2323](https://github.com/fern-api/fern/pull/2323)\
* Add test def for optional enum query param by @davidkonigsberg in [https://github.com/fern-api/fern/pull/2317](https://github.com/fern-api/fern/pull/2317)\
* chore: migrate to github workflows by @dsinghvi in [https://github.com/fern-api/fern/pull/2327](https://github.com/fern-api/fern/pull/2327)\
* chore: migrate documentation to core repo by @dsinghvi in [https://github.com/fern-api/fern/pull/2328](https://github.com/fern-api/fern/pull/2328)\
* feature: add example docs by @dsinghvi in [https://github.com/fern-api/fern/pull/2342](https://github.com/fern-api/fern/pull/2342)\
* Change 'let us know' link from email to issue by @zachkirsch in [https://github.com/fern-api/fern/pull/2344](https://github.com/fern-api/fern/pull/2344)\
* fix: links to generators by making them exact urls by @dannysheridan in [https://github.com/fern-api/fern/pull/2346](https://github.com/fern-api/fern/pull/2346)\
* feature: seed CLI runs compile commands for verification by @dsinghvi in [https://github.com/fern-api/fern/pull/2351](https://github.com/fern-api/fern/pull/2351)\
* Improvement: document using an enum name and value by @dannysheridan in [https://github.com/fern-api/fern/pull/2349](https://github.com/fern-api/fern/pull/2349)\
* chore: test definition for bearer auth with environment variable by @dsinghvi in [https://github.com/fern-api/fern/pull/2353](https://github.com/fern-api/fern/pull/2353)\
* fix: resolve referenced examples for path parameters by @dsinghvi in [https://github.com/fern-api/fern/pull/2356](https://github.com/fern-api/fern/pull/2356)\
\
## New Contributors\
\
* @davidkonigsberg made their first contribution in [https://github.com/fern-api/fern/pull/2317](https://github.com/fern-api/fern/pull/2317)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.3...0.15.4](https://github.com/fern-api/fern/compare/0.15.3...0.15.4)\
\
\
# November 21, 2023\
\
## 0.15.3\
\
**`(chore):`** ## What's Changed\
\
* fix: migrate from registry-node to fdr-sdk by @dsinghvi in [https://github.com/fern-api/fern/pull/2313](https://github.com/fern-api/fern/pull/2313)\
* build(deps): bump @redocly/openapi-core from 1.4.0 to 1.4.1 by @dependabot in [https://github.com/fern-api/fern/pull/2312](https://github.com/fern-api/fern/pull/2312)\
* build(deps): bump @fern-api/venus-api-sdk from 0.0.20-7-g6ea8dc4 to 0.0.36 by @dependabot in [https://github.com/fern-api/fern/pull/2311](https://github.com/fern-api/fern/pull/2311)\
* fix: docs preview server returns the proper load docs by url response by @dsinghvi in [https://github.com/fern-api/fern/pull/2315](https://github.com/fern-api/fern/pull/2315)\
* build(deps-dev): bump @types/swagger2openapi from 7.0.0 to 7.0.4 by @dependabot in [https://github.com/fern-api/fern/pull/2309](https://github.com/fern-api/fern/pull/2309)\
* feature: introduce `idempotency` configuration by @dsinghvi in [https://github.com/fern-api/fern/pull/2302](https://github.com/fern-api/fern/pull/2302)\
* chore: add `idempotency-headers` to fern  by @dsinghvi in [https://github.com/fern-api/fern/pull/2318](https://github.com/fern-api/fern/pull/2318)\
* chore: typescript generators depend on ir v31 by @dsinghvi in [https://github.com/fern-api/fern/pull/2320](https://github.com/fern-api/fern/pull/2320)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.2...0.15.3](https://github.com/fern-api/fern/compare/0.15.2...0.15.3)\
\
\
# November 20, 2023\
\
## 0.15.1\
\
**`(chore):`** *It's been forever since we released a non release candidate!*\
\
**Break**\
\
* The file structure of the Fern folder has now changed. If you have a single API, your definition can live directly at the top-level. If you have multiple, they will need to live in an apis folder. When you run `fern upgrade` the directory structure will automatically be updated.\
\
\
# November 17, 2023\
\
## 0.15.0-rc87\
\
**`(chore):`** ## What's Changed\
\
* fix: non .fernignored files are deleted on successive regeneration by @dsinghvi in [https://github.com/fern-api/fern/pull/2294](https://github.com/fern-api/fern/pull/2294)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.0-rc84...0.15.0-rc85](https://github.com/fern-api/fern/compare/0.15.0-rc84...0.15.0-rc85)\
\
\
# November 16, 2023\
\
## 0.15.0-rc82\
\
**`(chore):`** ## What's Changed\
\
* feature: introduce `x-fern-type` extension to the OpenAPI spec by @dsinghvi in [https://github.com/fern-api/fern/pull/2289](https://github.com/fern-api/fern/pull/2289)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.0-rc81...0.15.0-rc82](https://github.com/fern-api/fern/compare/0.15.0-rc81...0.15.0-rc82)\
\
\
# November 15, 2023\
\
## 0.15.0-rc79\
\
**`(chore):`** ## What's Changed\
\
* internal: Add more granular test definitions by @amckinney in [https://github.com/fern-api/fern/pull/2277](https://github.com/fern-api/fern/pull/2277)\
* feature: update fhir.yml and setup workflow for registration by @dsinghvi in [https://github.com/fern-api/fern/pull/2280](https://github.com/fern-api/fern/pull/2280)\
* fix: register union base properties in docs by @dsinghvi in [https://github.com/fern-api/fern/pull/2281](https://github.com/fern-api/fern/pull/2281)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.0-rc77...0.15.0-rc78](https://github.com/fern-api/fern/compare/0.15.0-rc77...0.15.0-rc78)\
\
\
# November 14, 2023\
\
## 0.15.0-rc76\
\
**`(chore):`** ## What's Changed\
\
* fix: OpenAPI importer handles parsing server variables by @dsinghvi in [https://github.com/fern-api/fern/pull/2275](https://github.com/fern-api/fern/pull/2275)\
\
**Full Changelog**: [https://github.com/fern-api/fern/compare/0.15.0-rc75...0.15.0-rc76](https://github.com/fern-api/fern/compare/0.15.0-rc75...0.15.0-rc76)\
\
\
# November 9, 2023\
\
## 0.15.0-rc71\
\
**`(chore):`** - CLI supports running typescript generators 0.8.1+ (@dsinghvi)\
\
\
# November 8, 2023\
\
## 0.15.0-rc70\
\
**`(chore):`** - Support a `x-fern-streaming` extension in the OpenAPI importer (@amckinney)\
\
\
# November 3, 2023\
\
## 0.15.0-rc66\
\
**`(chore):`** - **fix**: OpenAPI importer always uses tags to organize endpoints if present (@dsinghvi)\
\
\
# November 2, 2023\
\
## 0.15.0-rc64\
\
**`(chore):`** *No user facing changes*\
\
\
# November 1, 2023\
\
## 0.15.0-rc59\
\
**`(chore):`** fix: OpenAPI importer handles resolving property schema references (@dsinghvi)\
\
\
# October 30, 2023\
\
## 0.15.0-rc54\
\
**`(chore):`** - **feature**: OpenAPI importer supports resolving multi-file references (@dsinghvi)\
\
\
# October 28, 2023\
\
## 0.15.0-rc53\
\
**`(chore):`** - **feature**: OpenAPI importer supports `x-fern-header-variable-name` to customize the header name in the SDK\
\
\
# October 27, 2023\
\
## 0.15.0-rc51\
\
**`(chore):`** - **No user facing changes** - Seed testing CLI doesn't require generator languages to support testing OpenAPI/Postman generators\
\
\
# October 26, 2023\
\
## 0.15.0-rc50\
\
**`(chore):`** - Not a user facing change: IR for `property-response` uses correct typeId (@dsinghvi)\
\
\
# October 25, 2023\
\
## 0.15.0-rc48\
\
**`(chore):`** - Upgrade Go generator IR version (@amckinney)\
\
* `response-property` validation rules now handle aliases (@amckinney)\
\
\
# October 24, 2023\
\
## 0.15.0-rc47\
\
**`(chore):`** - Support `--custom fixture` in seed CLI for snapshot tests (@dsinghvi)\
\
\
# October 20, 2023\
\
## 0.15.0-rc43\
\
**`(chore):`** - Support reading examples from OpenAPI spec (@dsinghvi)\
\
\
# October 15, 2023\
\
## 0.15.0-rc42\
\
**`(chore):`** - Support generating preview url when generating docs (@dsinghvi)\
\
\
# October 13, 2023\
\
## 0.15.0-rc41\
\
**`(chore):`** - Rerelease SDKs (@dsinghvi)\
\
\
# October 11, 2023\
\
## 0.15.0-rc39\
\
**`(chore):`** - Support generating python snippets for documentation\
\
\
# October 10, 2023\
\
## 0.15.0-rc38\
\
**`(chore):`** - Additional seed test definitions (@dsinghvi)\
\
\
# October 8, 2023\
\
## 0.15.0-rc35\
\
**`(chore):`** - fix seed examples to contain datetime with UTC timezone (@dsinghvi)\
\
\
# October 6, 2023\
\
## 0.15.0-rc33\
\
**`(chore):`** - Read `const` values from OpenAPI spec (@dsinghvi)\
\
\
# October 5, 2023\
\
## 0.15.0-rc32\
\
**`(chore):`** - Fix discriminated union parsing in AsyncAPI import (@dsinghvi)\
\
\
# October 1, 2023\
\
## 0.15.0-rc30\
\
**`(chore):`** - Generator snapshot tester supports custom configs (@dsinghvi)\
\
\
# September 30, 2023\
\
## 0.15.0-rc29\
\
**`(chore):`** - `--local` mode of the Fern CLI now correctly copies over generated typescript code (@dsinghvi)\
\
\
# September 29, 2023\
\
## 0.15.0-rc28\
\
**`(chore):`** - Bump generator versions to the latest (@amckinney)\
\
* Send undiscriminated union type names to docs generation (@dsinghvi)\
\
\
# September 26, 2023\
\
## 0.15.0-rc27\
\
**`(chore):`** - Support `go-fiber` generator (@connormahon34)\
\
\
# September 25, 2023\
\
## 0.15.0-rc26\
\
**`(chore):`** - `fern generate --docs` will no longer fail because of network timeout issues (@dsinghvi)\
\
\
# September 20, 2023\
\
## 0.15.0-rc24\
\
**`(chore):`** - `fern generate --docs` runs validation on the the docs configuration (@dsinghvi)\
\
\
# September 19, 2023\
\
## 0.15.0-rc23\
\
**`(chore):`** - Support reading AsyncAPI Schemas (@dsinghvi)\
\
\
# September 18, 2023\
\
## 0.15.0-rc22\
\
**`(chore):`** - Add test definitions that contain examples(@amckinney)\
\
\
# September 17, 2023\
\
## 0.15.0-rc21\
\
**`(chore):`** - Only set GA availablity if explicitly defined in the API Definition (@dsinghvi)\
\
\
# September 16, 2023\
\
## 0.15.0-rc20\
\
**`(chore):`** - Set version slug override (@dsinghvi)\
\
\
# September 13, 2023\
\
## 0.15.0-rc18\
\
**`(chore):`** - CLI now requires that versioned navbars live in new files (@dsinghvi)\
\
* CLI supports sending availability (@dsinghvi)\
* CLI has new validation rules for mdx + filepaths (@dsinghvi)\
\
\
# September 10, 2023\
\
## 0.15.0-rc17\
\
**`(chore):`** - Docs support tabs (@dsinghvi)\
\
\
# September 9, 2023\
\
## 0.15.0-rc16\
\
**`(chore):`** - Fix and make sure CLI adheres to `--api` flag when filtering API workspaces (@dsinghvi)\
\
\
# September 6, 2023\
\
## 0.15.0-rc14\
\
**`(chore):`** - Support specifying instance when running docs generation `fern generate --docs --instance <url>`\
\
\
# September 5, 2023\
\
## 0.15.0-rc11\
\
**`(chore):`** - Latest java generators depend on IR v25 to support text/plain responses (@dsinghvi)\
\
\
# September 4, 2023\
\
## 0.15.0-rc10\
\
**`(chore):`** - OpenAPI importer supports reading `application/octet-stream` requests (@dsinghvi)\
\
\
# August 31, 2023\
\
## 0.15.0-rc6\
\
**`(chore):`** - Respect audiences for service type graph (@amckinney)\
\
\
# August 30, 2023\
\
## 0.15.0-rc4\
\
**`(chore):`** - fern.config.json version is set to `*` which allows easier integration with pnpm (@zachkirsch)\
\
* OpenAPI importer properly reads discriminated unions so that discriminants are stripped from subtypes (@dsinghvi)\
\
\
# August 25, 2023\
\
## 0.15.0-rc3\
\
**`(chore):`** - Support reading webhooks from OpenAPI specs (@dsinghvi)\
\
\
# August 23, 2023\
\
## 0.15.0-rc2\
\
**`(chore):`** - Support uploading images with custom content types such as SVGs (@dsinghvi)\
\
\
# August 18, 2023\
\
## 0.15.0-rc1\
\
**`(chore):`** - Update discriminated union detection to handle referenced schemas (@dsinghvi)\
\
\
# August 16, 2023\
\
## 0.15.0-rc0\
\
**`(chore):`** - **Break**: The fern directory now has a top-level `apis` directory to handle apis and docs no longer live within an api definition\
\
\
# August 14, 2023\
\
## 0.14.4-rc1\
\
**`(chore):`** Release 0.14.4-rc1\
\
\
# August 11, 2023\
\
## 0.14.4-rc0\
\
**`(chore):`** CLI handles property names that start with numbers for code generation (@dsinghvi)\
\
\
# August 8, 2023\
\
## 0.14.2\
\
**`(chore):`** - When running `fern init --openapi <openapi>` the OpenAPI generator wont be included (@dannysheridan)\
\
\
# August 7, 2023\
\
## 0.14.0\
\
**`(chore):`** - The latest Go SDK Generator depends on IR V22 (@amckinney)\
\
\
# August 5, 2023\
\
## 0.13.0-rc3\
\
**`(chore):`** - No changes\
\
\
# August 3, 2023\
\
## 0.13.0-rc2\
\
**`(chore):`** - Java generators now require IR V20 (@dsinghvi)\
\
\
# August 2, 2023\
\
## 0.11.12\
\
**`(chore):`** - Special case importing oneOf types that are all enums (@dsinghvi)\
\
\
# August 1, 2023\
\
## 0.11.12-rc2\
\
**`(chore):`** \\* Add `ServiceTypeReferenceInfo` to IR so that generators can recognize what types are referenced from exactly one service (@amckinney).\
\
```yaml\
  ServiceTypeReferenceInfo:\
    properties:\
      typesReferencedOnlyByService:\
        docs: "Types referenced by exactly one service."\
        type: map<commons.ServiceId, list<commons.TypeId>>\
      sharedTypes:\
        docs: "Types referenced by either zero or multiple services."\
        type: list<commons.TypeId>\
```\
\
\
# July 29, 2023\
\
## 0.11.12-rc1\
\
**`(chore):`** - Support `x-fern-ignore` OpenAPI extension. This extensions configures fern to ignore certain endpoints when generating SDKs. (@dsinghvi)\
\
```yaml\
paths: \
  my/endpoint/path: \
    get: \
      x-fern-ignore: true # <------- fern will skip this endpoint\
```\
\
\
# July 28, 2023\
\
## 0.11.11\
\
**`(chore):`** - OpenAPI importer handles converting numbers formatted as time-delta (@dsinghvi)\
\
\
# July 26, 2023\
\
## 0.11.10\
\
**`(chore):`** - OpenAPI importer handles converting servers with `staging` and `production` descriptions (@dsinghvi)\
\
* Generators are upgraded in fern init (@dannysheridan)\
* Documentation markdown paths are validated (@zachkirsch)\
\
\
# July 24, 2023\
\
## 0.11.9\
\
**`(chore):`** - handles `x-ndjson` content-type in OpenAPI responses\
\
\
# July 23, 2023\
\
## 0.11.7-rc8\
\
**`(chore):`** Release 0.11.7-rc8\
\
\
# July 22, 2023\
\
## 0.11.7-rc5\
\
**`(chore):`** Release 0.11.7-rc5\
\
\
# July 21, 2023\
\
## 0.11.7-rc4\
\
**`(chore):`** - Hacky release with sleep 5s before running docker\
\
\
# July 20, 2023\
\
## 0.11.7-rc3\
\
**`(chore):`** Release 0.11.7-rc3\
\
\
# July 18, 2023\
\
## 0.11.7-rc2\
\
**`(chore):`** - Pypi token is correctly read in for publishing\
\
\
# July 14, 2023\
\
## 0.11.7-rc1\
\
**`(chore):`** Release 0.11.7-rc1\
\
\
# July 13, 2023\
\
## 0.11.7-rc0\
\
**`(chore):`** Release 0.11.7-rc0\
\
\
# July 11, 2023\
\
## 0.11.6-rc0\
\
**`(chore):`** Release 0.11.6-rc0\
\
\
# July 10, 2023\
\
## 0.11.5\
\
**`(chore):`** - Fixes [https://github.com/fern-api/fern/issues/1880](https://github.com/fern-api/fern/issues/1880) (no longer forced to define auth if endpoints don't require auth)\
\
\
# July 6, 2023\
\
## 0.11.3-rc10\
\
**`(chore):`** Release 0.11.3-rc10\
\
\
# July 5, 2023\
\
## 0.11.3-rc4\
\
**`(chore):`** Release 0.11.3-rc4\
\
\
# June 28, 2023\
\
## 0.11.3-rc1\
\
**`(chore):`** - Support reading `x-fern-audiences` extension so that OpenAPI spec users can leverage fern audiences\
\
\
# June 24, 2023\
\
## 0.11.3-rc0\
\
**`(chore):`** Release 0.11.3-rc0\
\
\
# June 23, 2023\
\
## 0.11.2\
\
**`(chore):`** Release 0.11.2\
\
\
# June 22, 2023\
\
## 0.11.0\
\
**`(chore):`** - Update OpenAPI Importer logic to handle FastAPI operation ids\
\
\
# June 20, 2023\
\
## 0.10.27\
\
**`(chore):`** Release 0.10.27\
\
\
# June 15, 2023\
\
## 0.10.25\
\
**`(chore):`** Release 0.10.25\
\
\
# June 14, 2023\
\
## 0.10.25-rc1\
\
**`(chore):`** Release 0.10.25-rc1\
\
\
# June 13, 2023\
\
## 0.10.23\
\
**`(chore):`** Release 0.10.23\
\
\
# June 12, 2023\
\
## 0.10.19\
\
**`(chore):`** Release 0.10.19\
\
\
# June 11, 2023\
\
## 0.10.16\
\
**`(chore):`** Release 0.10.16\
\
\
# June 10, 2023\
\
## 0.10.14-rc0\
\
**`(chore):`** Release 0.10.14-rc0\
\
\
# June 9, 2023\
\
## 0.10.11\
\
**`(chore):`** Release 0.10.11\
\
\
# June 8, 2023\
\
## 0.10.10-rc0\
\
**`(chore):`** Release 0.10.10-rc0\
\
\
# June 7, 2023\
\
## 0.10.8-rc0\
\
**`(chore):`** Release 0.10.8-rc0\
\
\
# June 6, 2023\
\
## 0.10.3\
\
**`(chore):`** Release 0.10.3\
\
\
# June 5, 2023\
\
## 0.10.0\
\
**`(chore):`** - The docs `domain` must be a full domain ending in `docs.buildwithfern.com`\
\
* `docs.yml` now supports custom-domains so that docs can redirect from a custom url\
\
\
# June 2, 2023\
\
## 0.9.10\
\
**`(chore):`** Release 0.9.10\
\
\
# May 31, 2023\
\
## 0.9.9-rc0\
\
**`(chore):`** Release 0.9.9-rc0\
\
\
# May 30, 2023\
\
## 0.9.7-rc2\
\
**`(chore):`** Release 0.9.7-rc2\
\
\
# May 29, 2023\
\
## 0.9.6\
\
**`(chore):`** Release 0.9.6\
\
\
# May 28, 2023\
\
## 0.9.6-rc0\
\
**`(chore):`** Release 0.9.6-rc0\
\
\
# May 27, 2023\
\
## 0.9.4\
\
**`(chore):`** - `fern init` reads `FERN_TOKEN` if the user token is not available\
\
\
# May 25, 2023\
\
## 0.9.4-rc0\
\
**`(chore):`** Release 0.9.4-rc0\
\
\
# May 24, 2023\
\
## 0.9.2-rc3\
\
**`(chore):`** Release 0.9.2-rc3\
\
\
# May 23, 2023\
\
## 0.9.2-rc1\
\
**`(chore):`** Release 0.9.2-rc1\
\
\
# May 21, 2023\
\
## 0.9.2-rc0\
\
**`(chore):`** Release 0.9.2-rc0\
\
\
# May 20, 2023\
\
## 0.9.1-rc3\
\
**`(chore):`** Release 0.9.1-rc3\
\
\
# May 19, 2023\
\
## 0.9.1-rc2\
\
**`(chore):`** Release 0.9.1-rc2\
\
\
# May 18, 2023\
\
## 0.9.1-rc0\
\
**`(chore):`** Release 0.9.1-rc0\
\
\
# May 17, 2023\
\
## 0.9.0-rc0\
\
**`(chore):`** Release 0.9.0-rc0\
\
\
# May 16, 2023\
\
## 0.8.24\
\
**`(chore):`** Release 0.8.24\
\
\
# May 13, 2023\
\
## 0.8.21\
\
**`(chore):`** Release 0.8.21\
\
\
# May 12, 2023\
\
## 0.8.20-rc3\
\
**`(chore):`** Release 0.8.20-rc3\
\
\
# May 11, 2023\
\
## 0.8.19-rc8\
\
**`(chore):`** Release 0.8.19-rc8\
\
\
# May 10, 2023\
\
## 0.8.19-rc0\
\
**`(chore):`** Release 0.8.19-rc0\
\
\
# May 8, 2023\
\
## 0.8.16-rc10\
\
**`(chore):`** Release 0.8.16-rc10\
\
\
# May 7, 2023\
\
## 0.8.13-rc1\
\
**`(chore):`** Release 0.8.13-rc1\
\
\
# May 6, 2023\
\
## 0.8.13-rc0\
\
**`(chore):`** Release 0.8.13-rc0\
\
\
# May 5, 2023\
\
## 0.8.10\
\
**`(chore):`** Release 0.8.10\
\
\
# May 4, 2023\
\
## 0.8.7\
\
**`(chore):`** Release 0.8.7\
\
\
# May 3, 2023\
\
## 0.8.2\
\
**`(chore):`** Release 0.8.2\
\
\
# May 2, 2023\
\
## 0.7.5-rc17\
\
**`(chore):`** Release 0.7.5-rc17\
\
\
# May 1, 2023\
\
## 0.7.5-rc10\
\
**`(chore):`** Release 0.7.5-rc10\
\
\
# April 30, 2023\
\
## 0.7.5-rc1\
\
**`(chore):`** Release 0.7.5-rc1\
\
\
# April 28, 2023\
\
## 0.7.5-rc0\
\
**`(chore):`** Release 0.7.5-rc0\
\
\
# April 23, 2023\
\
## 0.7.1-rc0\
\
**`(chore):`** Release 0.7.1-rc0\
\
\
# April 21, 2023\
\
## 0.7.0-rc0\
\
**`(chore):`** Release 0.7.0-rc0\
\
\
# April 19, 2023\
\
## 0.6.11\
\
**`(chore):`** Release 0.6.11\
\
\
# April 17, 2023\
\
## 0.6.11-rc0\
\
**`(chore):`** Release 0.6.11-rc0\
\
\
# April 4, 2023\
\
## 0.6.10\
\
**`(chore):`** Release 0.6.10\
\
\
# April 3, 2023\
\
## 0.6.10-rc2\
\
**`(chore):`** Release 0.6.10-rc2\
\
\
# April 2, 2023\
\
## 0.6.8\
\
**`(chore):`** Release 0.6.8\
\
\
# April 1, 2023\
\
## 0.6.7-rc0\
\
**`(chore):`** Release 0.6.7-rc0\
\
\
# March 31, 2023\
\
## 0.6.5-rc1\
\
**`(chore):`** Release 0.6.5-rc1\
\
\
# March 30, 2023\
\
## 0.6.3-rc0\
\
**`(chore):`** Release 0.6.3-rc0\
\
\
# March 29, 2023\
\
## 0.6.2-rc1\
\
**`(chore):`** Release 0.6.2-rc1\
\
\
# March 28, 2023\
\
## 0.5.4-rc4\
\
**`(chore):`** Release 0.5.4-rc4\
\
\
# March 26, 2023\
\
## 0.5.4-rc3\
\
**`(chore):`** Release 0.5.4-rc3\
\
\
# March 24, 2023\
\
## 0.5.4-rc0\
\
**`(chore):`** Release 0.5.4-rc0\
\
\
# March 20, 2023\
\
## 0.5.3-rc6\
\
**`(chore):`** Release 0.5.3-rc6\
\
\
# March 19, 2023\
\
## 0.5.3-rc4\
\
**`(chore):`** Release 0.5.3-rc4\
\
\
# March 13, 2023\
\
## 0.5.3-rc2\
\
**`(chore):`** Release 0.5.3-rc2\
\
\
# March 11, 2023\
\
## 0.5.3-rc0\
\
**`(chore):`** Release 0.5.3-rc0\
\
\
# March 10, 2023\
\
## 0.5.2\
\
**`(chore):`** Release 0.5.2\
\
\
# March 9, 2023\
\
## 0.4.33-rc6\
\
**`(chore):`** Release 0.4.33-rc6\
\
\
# March 8, 2023\
\
## 0.4.33-rc1\
\
**`(chore):`** Release 0.4.33-rc1\
\
\
# March 7, 2023\
\
## 0.4.32-rc5\
\
**`(chore):`** Release 0.4.32-rc5\
\
\
# March 6, 2023\
\
## 0.4.32-rc1\
\
**`(chore):`** Release 0.4.32-rc1\
\
\
# March 5, 2023\
\
## 0.4.32-rc0\
\
**`(chore):`** Release 0.4.32-rc0\
\
\
# March 4, 2023\
\
## 0.4.31-rc1\
\
**`(chore):`** Release 0.4.31-rc1\
\
\
# March 3, 2023\
\
## 0.4.28-rc3\
\
**`(chore):`** Release 0.4.28-rc3\
\
\
# March 2, 2023\
\
## 0.4.27-rc1\
\
**`(chore):`** Release 0.4.27-rc1\
\
\
# March 1, 2023\
\
## 0.4.27-rc0\
\
**`(chore):`** Release 0.4.27-rc0\
\
\
# February 25, 2023\
\
## 0.4.25\
\
**`(chore):`** Release 0.4.25\
\
\
# February 23, 2023\
\
## 0.4.24\
\
**`(chore):`** Release 0.4.24\
\
\
# February 21, 2023\
\
## 0.4.24-rc1\
\
**`(chore):`** Release 0.4.24-rc1\
\
\
# February 20, 2023\
\
## 0.4.24-rc0\
\
**`(chore):`** Release 0.4.24-rc0\
\
\
# February 16, 2023\
\
## 0.4.23-rc0\
\
**`(chore):`** Release 0.4.23-rc0\
\
\
# February 12, 2023\
\
## 0.4.20\
\
**`(chore):`** Release 0.4.20\
\
\
# February 9, 2023\
\
## 0.4.19-rc0\
\
**`(chore):`** Release 0.4.19-rc0\
\
\
# February 7, 2023\
\
## 0.4.18\
\
**`(chore):`** Release 0.4.18\
\
\
# February 6, 2023\
\
## 0.4.15-rc0\
\
**`(chore):`** Release 0.4.15-rc0\
\
\
# February 5, 2023\
\
## 0.4.14\
\
**`(chore):`** Release 0.4.14\
\
\
# February 4, 2023\
\
## 0.4.13\
\
**`(chore):`** Release 0.4.13\
\
\
# February 2, 2023\
\
## 0.4.10\
\
**`(chore):`** Release 0.4.10\
\
\
# February 1, 2023\
\
## 0.4.5\
\
**`(chore):`** Release 0.4.5\
\
\
# January 31, 2023\
\
## 0.4.5-rc5\
\
**`(chore):`** Release 0.4.5-rc5\
\
\
# January 30, 2023\
\
## 0.4.2\
\
**`(chore):`** Release 0.4.2\
\
\
# January 29, 2023\
\
## 0.4.0-rc0\
\
**`(chore):`** Release 0.4.0-rc0\
\
\
# January 28, 2023\
\
## 0.3.21\
\
**`(chore):`** Release 0.3.21\
\
\
# January 27, 2023\
\
## 0.3.20\
\
**`(chore):`** Release 0.3.20\
\
\
# January 24, 2023\
\
## 0.3.19\
\
**`(chore):`** Release 0.3.19\
\
\
# January 23, 2023\
\
## 0.3.17-rc3\
\
**`(chore):`** Release 0.3.17-rc3\
\
\
# January 22, 2023\
\
## 0.3.17-rc2\
\
**`(chore):`** Release 0.3.17-rc2\
\
\
# January 21, 2023\
\
## 0.3.17-rc0\
\
**`(chore):`** Release 0.3.17-rc0\
\
\
# January 20, 2023\
\
## 0.3.16\
\
**`(chore):`** Release 0.3.16\
\
\
# January 19, 2023\
\
## 0.3.16-rc2\
\
**`(chore):`** Release 0.3.16-rc2\
\
\
# January 18, 2023\
\
## 0.3.12-rc12\
\
**`(chore):`** Release 0.3.12-rc12\
\
\
# January 17, 2023\
\
## 0.3.12-rc10\
\
**`(chore):`** Release 0.3.12-rc10\
\
\
# January 15, 2023\
\
## 0.3.12-rc4\
\
**`(chore):`** Release 0.3.12-rc4\
\
\
# January 13, 2023\
\
## 0.3.12-rc1\
\
**`(chore):`** Release 0.3.12-rc1\
\
\
# January 12, 2023\
\
## 0.3.11\
\
**`(chore):`** Release 0.3.11\
\
\
# January 11, 2023\
\
## 0.3.8-rc0\
\
**`(chore):`** Release 0.3.8-rc0\
\
\
# January 9, 2023\
\
## 0.3.8\
\
**`(chore):`** Release 0.3.8\
\
\
# January 8, 2023\
\
## 0.3.6\
\
**`(chore):`** Release 0.3.6\
\
\
# January 6, 2023\
\
## 0.3.6-rc0\
\
**`(chore):`** Release 0.3.6-rc0\
\
\
# December 28, 2022\
\
## 0.3.0\
\
**`(chore):`** Release 0.3.0\
\
\
# December 24, 2022\
\
## 0.3.0-rc12\
\
**`(chore):`** Release 0.3.0-rc12\
\
\
# December 23, 2022\
\
## 0.3.0-rc11\
\
**`(chore):`** Release 0.3.0-rc11\
\
\
# December 16, 2022\
\
## 0.3.0-rc1\
\
**`(chore):`** Release 0.3.0-rc1\
\
\
# December 15, 2022\
\
## 0.2.1\
\
**`(chore):`** Release 0.2.1\
\
\
# December 14, 2022\
\
## 0.1.3-rc8\
\
**`(chore):`** Release 0.1.3-rc8\
\
\
# December 13, 2022\
\
## 0.1.3-rc0\
\
**`(chore):`** Release 0.1.3-rc0\
\
\
# API Overview\
\
> Overview of the Fern API including usage and authentication\
\
The Fern API allows you to manage SDKs and code snippets using Fern's public RESTful API. API access is available on paid plans. [Reach out](https://buildwithfern.com/contact) to get started.\
\
## Accessing the Fern API\
\
Fern maintains official API clients for TypeScript and Python. We recommend using these clients, though the API supports any language or framework that sends HTTP requests.\
\
<CardGroup cols=\{2\}>\
  <Card title="TypeScript" icon=\{<img src="https://upload.wikimedia.org/wikipedia/commons/d/d9/Node.js_logo.svg" alt="Node.js logo"/>\} href="https://github.com/fern-api/typescript-sdk">\
    API client\
  </Card>\
\
  <Card title="Python" icon=\{<img src="https://upload.wikimedia.org/wikipedia/commons/c/c3/Python-logo-notext.svg" alt="Python logo"/>\} href="https://github.com/fern-api/python-sdk">\
    API client\
  </Card>\
</CardGroup>\
\
## Authentication\
\
Fern API requests require a bearer token for authentication. Use the CLI command [`fern token`](/learn/cli-api/cli-reference/commands#fern-token) to generate a bearer token. Tokens do not expire.\
\
\
# Get snippet for endpoint\
\
```http\
POST https://api.buildwithfern.com/snippets\
Content-Type: application/json\
```\
\
Get snippet by endpoint method and path\
\
\
\
## Request Body\
\
```json\
\{"type":"object","extends":[],"properties":[\{"key":"orgId","valueShape":\{"type":"alias","value":\{"type":"optional","shape":\{"type":"alias","value":\{"type":"id","id":"type_commons:OrgId"\}\}\}\},"description":"If the same API is defined across multiple organization,\\nyou must specify an organization ID.\\n"\},\{"key":"apiId","valueShape":\{"type":"alias","value":\{"type":"optional","shape":\{"type":"alias","value":\{"type":"id","id":"type_commons:ApiId"\}\}\}\},"description":"If you have more than one API, you must specify its ID.\\n"\},\{"key":"sdks","valueShape":\{"type":"alias","value":\{"type":"optional","shape":\{"type":"alias","value":\{"type":"list","itemShape":\{"type":"alias","value":\{"type":"id","id":"type_snippets:SDKRequest"\}\}\}\}\}\},"description":"The SDKs for which to load snippets. If unspecified,\\nsnippets for the latest published SDKs will be returned.\\n"\},\{"key":"endpoint","valueShape":\{"type":"alias","value":\{"type":"id","id":"type_commons:EndpointIdentifier"\}\}\},\{"key":"exampleIdentifier","valueShape":\{"type":"alias","value":\{"type":"optional","shape":\{"type":"alias","value":\{"type":"primitive","value":\{"type":"string"\}\}\}\}\},"description":"The identifier of the example to fetch the snippet for, this is ignored if a payload is passed in."\},\{"key":"payload","valueShape":\{"type":"alias","value":\{"type":"optional","shape":\{"type":"alias","value":\{"type":"id","id":"type_snippets:CustomSnippetPayload"\}\}\}\},"description":"The JSON payload to be used as the input for the code snippet. This should just be thought of as the\\nrequest body you'd be sending to the endpoint as a cURL. If not specified then the default payload will be used.\\n"\}]\}\
```\
\
## Response Body\
\
\
- 400: An ApiId is required\
- 400: An OrgId is required\
- 404: The requested OrgId and ApiId was not found\
- 404: The requested OrgId was not found\
- 404: The requested endpoint was not found\
- 404: The requested SDK was not found\
\
## Examples\
\
```shell\
curl -X POST https://api.buildwithfern.com/snippets \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "endpoint": \{\
    "path": "/v1/search",\
    "method": "GET"\
  \}\
\}'\
```\
\
```shell\
curl -X POST https://api.buildwithfern.com/snippets \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "endpoint": \{\
    "path": "string",\
    "method": "PUT"\
  \}\
\}'\
```\
\
```shell\
curl -X POST https://api.buildwithfern.com/snippets \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "endpoint": \{\
    "path": "string",\
    "method": "PUT"\
  \}\
\}'\
```\
\
```shell\
curl -X POST https://api.buildwithfern.com/snippets \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "endpoint": \{\
    "path": "string",\
    "method": "PUT"\
  \}\
\}'\
```\
\
```shell\
curl -X POST https://api.buildwithfern.com/snippets \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "endpoint": \{\
    "path": "string",\
    "method": "PUT"\
  \}\
\}'\
```\
\
```shell\
curl -X POST https://api.buildwithfern.com/snippets \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "endpoint": \{\
    "path": "string",\
    "method": "PUT"\
  \}\
\}'\
```\
\
```shell\
curl -X POST https://api.buildwithfern.com/snippets \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "endpoint": \{\
    "path": "string",\
    "method": "PUT"\
  \}\
\}'\
```\
\
```shell\
curl -X POST https://api.buildwithfern.com/snippets \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "endpoint": \{\
    "path": "string",\
    "method": "PUT"\
  \}\
\}'\
```\
\
```shell\
curl -X POST https://api.buildwithfern.com/snippets \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "endpoint": \{\
    "path": "string",\
    "method": "PUT"\
  \}\
\}'\
```\
\
```shell\
curl -X POST https://api.buildwithfern.com/snippets \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "endpoint": \{\
    "path": "string",\
    "method": "PUT"\
  \}\
\}'\
```\
\
# Load all snippets\
\
```http\
POST https://api.buildwithfern.com/snippets/load\
Content-Type: application/json\
```\
\
\
\
## Query Parameters\
\
- Page (optional)\
\
## Request Body\
\
```json\
\{"type":"object","extends":[],"properties":[\{"key":"orgId","valueShape":\{"type":"alias","value":\{"type":"optional","shape":\{"type":"alias","value":\{"type":"id","id":"type_commons:OrgId"\}\}\}\},"description":"If the same API is defined across multiple organization,\\nyou must specify an organization ID.\\n"\},\{"key":"apiId","valueShape":\{"type":"alias","value":\{"type":"optional","shape":\{"type":"alias","value":\{"type":"id","id":"type_commons:ApiId"\}\}\}\},"description":"If you have more than one API, you must specify its ID.\\n"\},\{"key":"sdks","valueShape":\{"type":"alias","value":\{"type":"optional","shape":\{"type":"alias","value":\{"type":"list","itemShape":\{"type":"alias","value":\{"type":"id","id":"type_snippets:SDKRequest"\}\}\}\}\}\},"description":"The SDKs for which to load snippets. If unspecified,\\nsnippets for the latest published SDKs will be returned.\\n"\}]\}\
```\
\
## Response Body\
\
\
- 400: Page must be >=1\
- 400: An ApiId is required\
- 400: An OrgId is required\
- 404: The requested OrgId and ApiId was not found\
- 404: The requested OrgId was not found\
- 404: The requested SDK was not found\
\
## Examples\
\
```shell\
curl -X POST "https://api.buildwithfern.com/snippets/load?page=1" \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "orgId": "vellum",\
  "apiId": "vellum-ai",\
  "sdks": [\
    \{\
      "type": "python",\
      "package": "vellum-ai"\
    \}\
  ]\
\}'\
```\
\
```shell\
curl -X POST "https://api.buildwithfern.com/snippets/load?page=0" \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\}'\
```\
\
```shell\
curl -X POST "https://api.buildwithfern.com/snippets/load?page=0" \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\}'\
```\
\
```shell\
curl -X POST "https://api.buildwithfern.com/snippets/load?page=0" \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\}'\
```\
\
```shell\
curl -X POST "https://api.buildwithfern.com/snippets/load?page=0" \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\}'\
```\
\
```shell\
curl -X POST "https://api.buildwithfern.com/snippets/load?page=0" \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\}'\
```\
\
```shell\
curl -X POST "https://api.buildwithfern.com/snippets/load?page=0" \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\}'\
```\
\
```shell\
curl -X POST "https://api.buildwithfern.com/snippets/load?page=0" \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\}'\
```\
\
```shell\
curl -X POST "https://api.buildwithfern.com/snippets/load?page=0" \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\}'\
```\
\
```shell\
curl -X POST "https://api.buildwithfern.com/snippets/load?page=0" \\\
     -H "Authorization: Bearer <token>" \\\
     -H "Content-Type: application/json" \\\
     -d '\{\}'\
```\
\
# Generate Token\
\
```http\
POST https://api.buildwithfern.com/tokens/generate\
Content-Type: application/json\
```\
\
Generate a token\
\
\
\
## Request Body\
\
```json\
\{"type":"object","extends":[],"properties":[\{"key":"orgId","valueShape":\{"type":"alias","value":\{"type":"id","id":"type_commons:OrgId"\}\},"description":"The organization to generate a token for.\\n"\},\{"key":"scope","valueShape":\{"type":"alias","value":\{"type":"primitive","value":\{"type":"string"\}\}\},"description":"The scope of the token. Valid scopes include: \\n  - admin \\n  - sdk:read:\{package_name\}\\n"\}]\}\
```\
\
## Response Body\
\
\
\
## Examples\
\
```shell\
curl -X POST https://api.buildwithfern.com/tokens/generate \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "orgId": "orgId",\
  "scope": "scope"\
\}'\
```\
\
# Revoke Token\
\
```http\
POST https://api.buildwithfern.com/tokens/revoke\
Content-Type: application/json\
```\
\
Revoke a token\
\
\
\
## Request Body\
\
```json\
\{"type":"object","extends":[],"properties":[\{"key":"orgId","valueShape":\{"type":"alias","value":\{"type":"id","id":"type_commons:OrgId"\}\},"description":"The organization to create snippets for.\\n"\},\{"key":"tokenId","valueShape":\{"type":"alias","value":\{"type":"id","id":"type_commons:TokenId"\}\}\}]\}\
```\
\
## Examples\
\
```shell\
curl -X POST https://api.buildwithfern.com/tokens/revoke \\\
     -H "Content-Type: application/json" \\\
     -d '\{\
  "orgId": "orgId",\
  "tokenId": "tokenId"\
\}'\
```\
}