/vellum-client-generator

Vellum’s Fern API which is used to generate SDKs.

Primary LanguageMDX

Vellum API

Tagging a release on this repository will update the following clients:

What is in this repository?

This repository contains

  • Vellum's Fern API Definition which lives in the definition folder
  • Generators (see generators.yml)
  • Definition for Help Documentation

What is in the API Definition?

The API Definition contains an OpenAPI Specification adapted to be compatible with Fern.

To make sure that the definition is valid, you can use the Fern CLI.

npm install -g fern-api # Installs CLI
fern check # Checks if the definition is valid

What are generators?

Generators read in your API Definition and output artifacts (e.g. the TypeScript SDK Generator) and are tracked in generators.yml.

To trigger the generators run:

# output generated files locally
fern generate

# publish generated files
fern generate --group publish --version <version>

The publish command currently runs in a GitHub workflow (see ci.yml)

Publishing new client versions

Here are the steps required to publish a new version of our API clients.

  1. cd into the django directory from within the main vellum repo
  2. Run make generate-swagger-all
  3. Open the generated schema_api_client_v1.yaml file
  4. Copy the contents of the file and paste it into the definition within this repo: fern/openapi/openapi.yaml
  5. Optionally run fern check to make sure all is good.
  6. Optionally run fern generate to see the newly generated clients locally.
    • If this is your first time, fern will ask you to log in. Hit Y to proceed logging in through GitHub.
  7. Commit and push the changes to a new branch an open a PR
  8. Upon approval by at least one other reviewer, merge the branch into main.
  9. Create a new Release within Github. This will trigger a github action that will publish the new clients to their respective repos.

Upgrading Fern

You can use the following command to upgrade fern to the latest version:

fern upgrade --rc

Docs Site

Fern hosts our docs site at https://docs.vellum.ai/. The site navigation and page structure is defined by the docs.yml file. The content for each page is defined in the help folder as .mdx files using markdown syntax.

Static Assets

Fern is in the process of adding support for relative links to static assets like images. In the meantime, we host all images ourselves in this public GCS bucket.

Custom Components

You'll notice the usage of some custom components like CodeBlock. These are specific to fern.

Local Development

Fern has not yet released a mechanism to locally compile and preview the docs site. In the meantime, you can deploy to our staging site to preview your changes (see below for deploying to staging).

Deploying the Docs Site

You can publish the docs to the staging site by running the following command:

fern generate --docs --instance vellum-staging.docs.buildwithfern.com

The staging site can be found at vellum-staging.docs.buildwithfern.com.

You can publish the docs to production by running:

fern generate --docs --instance vellum.docs.buildwithfern.com

The production site can be found at docs.vellum.ai.

Troubleshooting

If you run into errors, you can add the --log-level debug flag to get more information.

If you get a 403 error, you may need to first run fern login. You might also need to be added to the Vellum org in Fern, which requires contacting the fern team in #fern-x-vellum in Slack.