How to generate scripts from an OpenAPI spec and sync them with your workspace

1. Setup your local development environment of your Windmill workspace

mkdir [workspace_name]
cd [workspace_name]
wmill workspace add [workspace_name] [workspace_id] [remote]
wmill sync pull

2. Generate the scripts using @windmill-labs/openapi-codegen-cli:

Minimal example:

bunx @windmill-labs/openapi-codegen-cli --schemaUrl "urlOrLocalOpenApiSpecInJsonOrYaml" --outputDir "./" --resourceTypeName "resourceTypeNameForThisSpec" --authKind "bearer"

Schema url (required)

The schema url can be a local file or a remote url. It can be a json or yaml file.

Output directory (required)

The output directory is specified by the --outputDir flag. The scripts will be generated in this directory.

Resource type name (required unless no auth and extra params/headers)

The resource type will be generated with the necessary properties. The resource type name is specified by the --resourceTypeName flag.

Auth (required)

No auth

For no authentication, pass the --authKind none. The resource type will be omitted if no extra resource type params or extra headers are specified.

Bearer auth

For bearer authentication, pass the --authKind bearer. It will define a token property on the resource type. You can change the name of the token property by passing the --tokenName "token" flag. You can change the "Bearer" prefix by passing a --tokenPrefix myprefix flag, a space will be added between the prefix and the token.

Basic auth

For basic authentication, pass the --authKind basic flag. By default, it will add "username" and "password" to the resource type. You can change the names of the properties in the resource type by passing the --usernameName "username" and --passwordName "password" flags. You can change the "Basic" prefix by passing a --tokenPrefix myprefix flag, a space will be added between the prefix and the token.

Query auth

For query authentication, pass the --authKind query flag. By default, it will add a token property on the resource type and pass the token as a query parameter named "token". Setting tokenName will change the name of the token property as well as the name of the query parameter.

Header auth

For header authentication, pass the --authKind header flag and the --headerName "X-CUSTOM-HEADER" flag. Like for bearer and query auth, it will add a token property to the resource type. You can change the name of the token property in the resource type by passing the --tokenName "token" flag. You can add a prefix to the header value by passing the --tokenPrefix myprefix flag, a space will be added between the prefix and the token.

Override base url

Instead of using the base url from the spec file, you can override it by passing the --baseUrl "https://api.example.com" flag.

Extra resource type params for path params

You can specify parameters of the path to be included in the resource type by adding the --extraResourceParams "extraParameter1,extraParameter2" flag. The generated script path will use the resource type properties instead of taking them as parameters. This is useful when you have a path parameter (e.g. {subdomain}, {organisation_id}, etc...) that is common to all endpoints of the spec and you don't want to pass it as a parameter in each script.

Extra headers

You can also specify extra headers to be passed to each request by adding the --extraHeaders "header1:propertyName1,header2:propertyName2" flag. Those property names will be added to the resource type.

Specifying tags

You can limit the CLI to only generate scripts for a subset of the spec tags by passing the --tags "tag1,tag2" flag.

3. Sync your generated scripts with the remote by running wmill sync push.

Full example with the Github API

# assume we have a workspace called CodegenDemo with id codegendemo on the cloud
mkdir CodegenDemo
cd CodegenDemo
wmill workspace add CodegenDemo codegendemo https://app.windmill.dev
wmill sync pull

# generate the scripts from the github OpenAPI spec into the f/github folder
bunx @windmill-labs/openapi-codegen-cli \
  --schemaUrl "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json" \
  --outputDir "./f/github" \
  --resourceTypeName "github" \
  --authKind "bearer"


# sync the scripts with the remote
wmill sync push

Validate OpenAPI spec

You can validate an OpenAPI spec by running the following command:

bunx @windmill-labs/openapi-codegen-cli validate "urlOrLocalOpenApiSpecInJsonOrYaml"