diff --git a/fern/products/sdks/overview/go/configuration.mdx b/fern/products/sdks/overview/go/configuration.mdx index 2f92fa332..1ba4d67f3 100644 --- a/fern/products/sdks/overview/go/configuration.mdx +++ b/fern/products/sdks/overview/go/configuration.mdx @@ -4,5 +4,3 @@ description: Configuration options for the Fern Go SDK. --- # Go Configuration - -Discover how to configure the Fern Go SDK for your project. \ No newline at end of file diff --git a/fern/products/sdks/overview/python/quickstart.mdx b/fern/products/sdks/overview/python/quickstart.mdx index 9aa5e689f..c26144140 100644 --- a/fern/products/sdks/overview/python/quickstart.mdx +++ b/fern/products/sdks/overview/python/quickstart.mdx @@ -3,6 +3,65 @@ title: Python Quickstart description: Get started quickly with the Fern Python SDK. --- -# Python Quickstart + -Follow these steps to quickly get up and running with the Fern Python SDK. \ No newline at end of file +Generate a Python SDK by following the instructions on this page. + + + + + ### Initialize the Fern Folder + + You can use either the OpenAPI definition, AsyncAPI definition, or Fern + Definition to generate your SDK. + + + + + + + + + + + + +### Add the SDK generator + +Add the Python SDK generator: + +```bash +fern add fern-python-sdk --group sdk +``` + +This command adds the following to `generators.yml`: + +```yaml + sdk: + generators: + - name: fernapi/fern-python-sdk + version: + output: + location: local-file-system + path: ../sdks/python +``` + + + +```bash +fern/ # created in step 1 +sdks/ # created by fern generate --group sdk +├─ python + ├─ __init__.py + ├─ client.py + ├─ core/ + └─ imdb/ # or the name of your API + ├─ errors/ + └─ types/ +``` + +Some files, including `pyproject.toml` and `README.md`, are only generated on paid plans. +To get the fully generated SDK, schedule a + [demo](https://buildwithfern.com/contact) or [email + us](mailto:support@buildwithfern.com). + diff --git a/fern/products/sdks/overview/typescript/quickstart.mdx b/fern/products/sdks/overview/typescript/quickstart.mdx index 9fdf98762..3c64cad90 100644 --- a/fern/products/sdks/overview/typescript/quickstart.mdx +++ b/fern/products/sdks/overview/typescript/quickstart.mdx @@ -3,208 +3,61 @@ title: TypeScript Quickstart description: Get started quickly with the Fern Typescript SDK. --- - - 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. - + Generate a TypeScript SDK by following the instructions on this page. - ### Install the Fern CLI - - Run the following command to install the CLI tool or update it to the latest version: - - ```bash - npm install -g fern-api - ``` + ### Initialize the Fern Folder You can use either the OpenAPI definition, AsyncAPI definition, or Fern Definition to generate your SDK. - - Initialize the Fern folder using your OpenAPI Specification. Run one of the following commands based on your spec's location. - - - Fern can handle both JSON and YML formats for OpenAPI specifications, and the --openapi flag accepts either format, so you can use whichever format your API spec is available in. - - - - `--organization ` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK. - - - - - - ```bash - fern init --openapi path/to/openapi.yml --organization - ``` - - - - ```bash - fern init --openapi https://api.example.com/openapi.yml --organization - ``` - - - - - This creates a `fern` folder in your current directory with the OpenAPI Specification. The exact folder structure might look different depending on your initial input files. - - ```bash - fern/ - ├─ fern.config.json # root-level configuration - └─ api/ # your API - ├─ generators.yml # generators you're using - └─ openapi/ - ├─ openapi.yml # API-level configuration - ``` - - - Initialize the Fern folder using your AsyncAPI Specification. Run one of the following commands based on your spec's location. - - - Fern can handle both JSON and YML formats for AsyncAPI specifications, and the --openapi flag accepts either format, so you can use whichever format your API spec is available in. - - - - `--organization ` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK. - - - - - - ```bash - fern init --asyncapi path/to/asyncapi.yml --organization - ``` - - - - ```bash - fern init --asyncapi https://api.example.com/asyncapi.yml --organization - ``` - - - - - This creates a `fern` folder in your current directory with the AsyncAPI Specification. The exact folder structure might look different depending on your initial input files. - - ```bash - fern/ - ├─ fern.config.json # root-level configuration - └─ api/ # your API - ├─ generators.yml # generators you're using - └─ openapi/ - ├─ openapi.yml # API-level configuration - ``` - - - - 1. Initialize the Fern folder using the Fern Definition by running the following command: - - ```bash - fern init --organization - ``` - - - `--organization ` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK. - - - This creates a `fern` folder in your current directory with the Fern Definition. - - ```bash - fern/ - ├─ fern.config.json # root-level configuration - ├─ generators.yml # generators you're using - └─ definition/ - ├─ api.yml # API-level configuration - └─ imdb.yml # endpoints, types, and errors - ``` - - - `imdb.yml` contains an example movies API. If you’re just generating an SDK for test purposes, you can leave this file as it is. To generate an SDK for your own API instead of the example movies API, replace `imdb.yml` with your own endpoints, types, and errors before proceeding with the rest of this page. - - - {/* TODO: show want generators.yml looks like, link out to configuration.md */} - - 1. Add the config option `outputSourceFiles: true` to `generators.yml`. This ensures your SDK contains `.ts` files instead of compiled output. - - ```yaml {11-12} - # yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json - default-group: local - groups: - local: - generators: - - name: fernapi/fern-typescript-node-sdk - output: - location: local-file-system - path: ../sdks/typescript - version: - config: - outputSourceFiles: true - ``` - - + + + + - - ### Pass `fern check` - - Run `fern check` to ensure that your API Definition is valid. If there are any errors, - fix them before proceeding. - - - If you're using an OpenAPI Specification, check out all of our - [supported extensions](/learn/api-definition/openapi/extensions). - - - ### Add the SDK generator - - Add the TypeScript SDK generator: - - ```bash - fern add fern-typescript-node-sdk --group sdk - ``` - - This command adds the following to `generators.yml`: - - ```yaml - sdk: - generators: - - name: fernapi/fern-typescript-node-sdk - version: - output: - location: local-file-system - path: ../sdks/typescript - ``` - ### Generate the SDK - - Generate the SDK: - - ```bash - fern generate --group sdk - ``` - - This creates a `sdks` folder in your current directory. The resulting folder structure looks like this: - - - ```bash - fern/ # created in step 1 - sdks/ # created by fern generate --group sdk - ├─ typescript - ├─ cjs/ - ├─ api/ - ├─ core/ - └─ errors/ - └─ esm/ - ├─ api/ - ├─ core/ - └─ errors/ - ``` + + +### Add the SDK generator + +Add the TypeScript SDK generator: + +```bash +fern add fern-typescript-node-sdk --group sdk +``` + +This command adds the following to `generators.yml`: + +```yaml + sdk: + generators: + - name: fernapi/fern-typescript-node-sdk + version: + output: + location: local-file-system + path: ../sdks/typescript +``` + + +```bash +fern/ # created in step 1 +sdks/ # created by fern generate --group sdk + ├─ typescript + ├─ cjs/ + ├─ api/ + ├─ core/ + └─ errors/ + └─ esm/ + ├─ api/ + ├─ core/ + └─ errors/ +``` diff --git a/fern/products/sdks/snippets/demo-warning.mdx b/fern/products/sdks/snippets/demo-warning.mdx new file mode 100644 index 000000000..c8cb5e42a --- /dev/null +++ b/fern/products/sdks/snippets/demo-warning.mdx @@ -0,0 +1,5 @@ + + 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. + \ No newline at end of file diff --git a/fern/products/sdks/snippets/generate-sdk.mdx b/fern/products/sdks/snippets/generate-sdk.mdx new file mode 100644 index 000000000..9342d5580 --- /dev/null +++ b/fern/products/sdks/snippets/generate-sdk.mdx @@ -0,0 +1,9 @@ +### Generate the SDK + + Generate the SDK: + + ```bash + fern generate --group sdk + ``` + + This creates a `sdks` folder in your current directory. The resulting folder structure looks like this: \ No newline at end of file diff --git a/fern/products/sdks/snippets/install-cli.mdx b/fern/products/sdks/snippets/install-cli.mdx new file mode 100644 index 000000000..33c5a2955 --- /dev/null +++ b/fern/products/sdks/snippets/install-cli.mdx @@ -0,0 +1,7 @@ +### Install the Fern CLI + + Run the following command to install the CLI tool or update it to the latest version: + + ```bash + npm install -g fern-api + ``` \ No newline at end of file diff --git a/fern/products/sdks/snippets/option-1-openapi.mdx b/fern/products/sdks/snippets/option-1-openapi.mdx new file mode 100644 index 000000000..d9aaf5011 --- /dev/null +++ b/fern/products/sdks/snippets/option-1-openapi.mdx @@ -0,0 +1,38 @@ + + Initialize the Fern folder using your OpenAPI Specification. Run one of the following commands based on your spec's location. + + + Fern can handle both JSON and YML formats for OpenAPI specifications, and the --openapi flag accepts either format, so you can use whichever format your API spec is available in. + + + + `--organization ` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK. + + + + + + ```bash + fern init --openapi path/to/openapi.yml --organization + ``` + + + + ```bash + fern init --openapi https://api.example.com/openapi.yml --organization + ``` + + + + + This creates a `fern` folder in your current directory with the OpenAPI Specification. The exact folder structure might look different depending on your initial input files. + + ```bash + fern/ + ├─ fern.config.json # root-level configuration + └─ api/ # your API + ├─ generators.yml # generators you're using + └─ openapi/ + ├─ openapi.yml # API-level configuration + ``` + \ No newline at end of file diff --git a/fern/products/sdks/snippets/option-2-asyncapi.mdx b/fern/products/sdks/snippets/option-2-asyncapi.mdx new file mode 100644 index 000000000..c4b5b0e04 --- /dev/null +++ b/fern/products/sdks/snippets/option-2-asyncapi.mdx @@ -0,0 +1,38 @@ + + Initialize the Fern folder using your AsyncAPI Specification. Run one of the following commands based on your spec's location. + + + Fern can handle both JSON and YML formats for AsyncAPI specifications, and the --openapi flag accepts either format, so you can use whichever format your API spec is available in. + + + + `--organization ` configures your organization name in `fern.config.json`. This is required in order to successfully generate your SDK. + + + + + + ```bash + fern init --asyncapi path/to/asyncapi.yml --organization + ``` + + + + ```bash + fern init --asyncapi https://api.example.com/asyncapi.yml --organization + ``` + + + + + This creates a `fern` folder in your current directory with the AsyncAPI Specification. The exact folder structure might look different depending on your initial input files. + + ```bash + fern/ + ├─ fern.config.json # root-level configuration + └─ api/ # your API + ├─ generators.yml # generators you're using + └─ openapi/ + ├─ openapi.yml # API-level configuration + ``` + \ No newline at end of file diff --git a/fern/products/sdks/snippets/option-3-fern-def.mdx b/fern/products/sdks/snippets/option-3-fern-def.mdx new file mode 100644 index 000000000..65ff4ffd0 --- /dev/null +++ b/fern/products/sdks/snippets/option-3-fern-def.mdx @@ -0,0 +1,56 @@ + +1. Initialize the Fern folder using the Fern Definition by running the following command: + + ```bash + fern init --organization + ``` + + `--organization ` configures your organization + name in `fern.config.json`. This is required in order to successfully + generate your SDK. + + This creates a `fern` folder in your current directory with the Fern Definition. + + ```bash + fern/ + ├─ fern.config.json # root-level configuration + ├─ generators.yml # generators you're using + └─ definition/ + ├─ api.yml # API-level configuration + └─ imdb.yml # endpoints, types, and errors + ``` + + `imdb.yml` contains an example movies API. If you’re just + generating an SDK for test purposes, you can leave this file as it is. To + generate an SDK for your own API instead of the example movies API, + replace `imdb.yml` with your own endpoints, types, and errors before + proceeding with the rest of this page. + + {/* TODO: show what generators.yml looks like, link out to configuration.md */} + +2. Add the config option `outputSourceFiles: true` to + `generators.yml`. This ensures your SDK contains source files in + your preferred SDK language instead of compiled output. + + ```yaml {11-12} + # yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json + default-group: local + groups: + local: + generators: + - name: fernapi/fern-typescript-node-sdk + output: + location: local-file-system + path: ../sdks/typescript + version: + config: + outputSourceFiles: true + ``` + + `fern init` creates a default configuration that includes the + TypeScript Node SDK generator. The `local` group containing this + generator only generates if you run fern generate without specifying a + group, or if you explicitly target it with `fern generate --group + local`. In subsequent steps, you'll add an additional generator for your + preferred SDK language. + \ No newline at end of file diff --git a/fern/products/sdks/snippets/pass-fern-check.mdx b/fern/products/sdks/snippets/pass-fern-check.mdx new file mode 100644 index 000000000..68e70fb30 --- /dev/null +++ b/fern/products/sdks/snippets/pass-fern-check.mdx @@ -0,0 +1,9 @@ + ### Pass `fern check` + + Run `fern check` to ensure that your API Definition is valid. If there are any errors, + fix them before proceeding. + + + If you're using an OpenAPI Specification, check out all of our + [supported extensions](/learn/api-definition/openapi/extensions). + \ No newline at end of file