From d1c5d0997b5b9f7acb3bc80f844ac3f513f8fe69 Mon Sep 17 00:00:00 2001 From: dannysheridan Date: Sun, 2 Jun 2024 19:10:18 -0400 Subject: [PATCH 1/7] docs: add a tab for server code generation --- fern/docs.yml | 17 +++++++++++++++++ fern/pages/servers/express.mdx | 0 fern/pages/servers/fastapi.mdx | 0 fern/pages/servers/introduction.mdx | 0 fern/pages/servers/spring.mdx | 0 fern/pages/welcome.mdx | 11 +++++++++-- 6 files changed, 26 insertions(+), 2 deletions(-) create mode 100644 fern/pages/servers/express.mdx create mode 100644 fern/pages/servers/fastapi.mdx create mode 100644 fern/pages/servers/introduction.mdx create mode 100644 fern/pages/servers/spring.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 93dd5d69afa..8d055c2212d 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -27,6 +27,9 @@ tabs: sdks: display-name: SDKs slug: sdks + servers: + display-name: Servers + slug: servers cli-api: display-name: CLI & API Reference slug: cli-api @@ -271,6 +274,20 @@ navigation: path: ./pages/docs/components/endpoint-response-snippet.mdx icon: "turn-down" slug: response-snippet + - tab: servers + layout: + - section: Introduction + contents: + - page: What is server code generation? + path: ./pages/servers/introduction.mdx + - section: Server Frameworks + contents: + - page: FastAPI server + path: ./pages/servers/fastapi.mdx + - page: Spring server + path: ./pages/servers/spring.mdx + - page: Express server + path: ./pages/servers/express.mdx - tab: cli-api layout: - section: CLI Reference diff --git a/fern/pages/servers/express.mdx b/fern/pages/servers/express.mdx new file mode 100644 index 00000000000..e69de29bb2d diff --git a/fern/pages/servers/fastapi.mdx b/fern/pages/servers/fastapi.mdx new file mode 100644 index 00000000000..e69de29bb2d diff --git a/fern/pages/servers/introduction.mdx b/fern/pages/servers/introduction.mdx new file mode 100644 index 00000000000..e69de29bb2d diff --git a/fern/pages/servers/spring.mdx b/fern/pages/servers/spring.mdx new file mode 100644 index 00000000000..e69de29bb2d diff --git a/fern/pages/welcome.mdx b/fern/pages/welcome.mdx index 48d9032197d..4a6d32af8b5 100644 --- a/fern/pages/welcome.mdx +++ b/fern/pages/welcome.mdx @@ -7,13 +7,13 @@ layout: overview ## Products - + - Start with an API Definition + Develop your API before developing your application Idiomatic client libraries + + Generate server-side code from your API definition + ## Motivation From e0a6703e6d7bc76d80b7fd9f85d16d499cc0f4b5 Mon Sep 17 00:00:00 2001 From: dannysheridan Date: Sun, 2 Jun 2024 23:22:45 -0400 Subject: [PATCH 2/7] start express page --- fern/pages/servers/express.mdx | 79 ++++++++++++++++++++++++++++++++++ fern/pages/welcome.mdx | 22 +++++----- 2 files changed, 91 insertions(+), 10 deletions(-) diff --git a/fern/pages/servers/express.mdx b/fern/pages/servers/express.mdx index e69de29bb2d..1946cc67857 100644 --- a/fern/pages/servers/express.mdx +++ b/fern/pages/servers/express.mdx @@ -0,0 +1,79 @@ +--- +title: Express.js +description: +subtite: Generate types and networking logic for your Express server. +slug: express +--- + +Express is a minimal and flexible Node.js web application framework. It is a popular choice for building APIs and web servers. + +Fern generates TypeScript types and networking logic for your Express server. This saves you time and adds compile-time safety by guaranteeing that you are serving the exact API that you specified in your API definition. + +## What gets generated? + +- TypeScript interfaces for your API types +- Exceptions that you can throw for non-200 responses +- Interfaces for you to define your business logic +- All the networking/HTTP logic to call your API + +## Getting started + +Clone the [starter repo](https://github.com/fern-api/express-starter/) for Express + React. + +## Demo video + +Learn how Fern can be helpful when building an Express server. + + + +## Getting started + + +```yaml +groups: + express-server: + generators: + - name: fernapi/fern-typescript-express + version: 0.15.0 + output: + location: local-file-system + path: ../app/server +``` + + +Make sure to enable `allowSyntheticDefaultImports` in your `tsconfig.json` when using this generator. + +## Configurations + +The following options are supported when generating an Express server. + +### `useBrandedStringAliases` + +### `treatUnknownAsAny` + +### `noSerdeLayer` + +### `outputSourceFiles` + +### `areImplementationsOptional` + +**Type**: boolean ** +Default:** false + +By default, the generated register() will require an implementatiion for every service defined in your Fern Definition. + +If areImplementationsOptional is enabled, then register() won't require any implementations. Note that this is mildly dangerous: if you forget to include an implementation, then your server behavior may drift from your docs and clients. + +### `doNotHandleUnrecognizedErrors` + +**Type**: boolean +**Default**: false + +By default, if you throw a non-Fern error in your endpoint handler, it will be caught by generated code and a `500` response will be returned. No details from the error will be leaked to the client. + +If doNotHandleUnrecognizedErrors is enabled and you throw a non-Fern error, the error will be caught and passed on with `next(error)`. It's your responsibility to set up error-catching middleware that handles the error and returns a response to the client. + + + + + diff --git a/fern/pages/welcome.mdx b/fern/pages/welcome.mdx index 4a6d32af8b5..04876e47d25 100644 --- a/fern/pages/welcome.mdx +++ b/fern/pages/welcome.mdx @@ -5,45 +5,47 @@ slug: home layout: overview --- +APIs underpin the internet but are still painful to work with. They are often untyped, unstandardized, and out-of-sync across multiple sources of truth. + +Fern is a developer tool designed to generate SDKs, documentation, and servers from an API definition. Build with Fern to offer easy-to-use and well-documented APIs. + ## Products - + - Develop your API before developing your application + Design your API before building your app A beautiful documentation website Idiomatic client libraries - Generate server-side code from your API definition + Generate server-side code ## Motivation
- 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. + 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. From 73da05f74a8d9189d0c08efe24f0dad1f86677d2 Mon Sep 17 00:00:00 2001 From: dannysheridan Date: Mon, 3 Jun 2024 23:11:35 -0400 Subject: [PATCH 3/7] drafts of fastapi, spring, and express --- fern/pages/servers/express.mdx | 134 ++++++++++++++++++++++------ fern/pages/servers/fastapi.mdx | 132 +++++++++++++++++++++++++++ fern/pages/servers/introduction.mdx | 22 +++++ fern/pages/servers/spring.mdx | 123 +++++++++++++++++++++++++ fern/pages/welcome.mdx | 23 +++-- 5 files changed, 397 insertions(+), 37 deletions(-) diff --git a/fern/pages/servers/express.mdx b/fern/pages/servers/express.mdx index 1946cc67857..ab08c20b6aa 100644 --- a/fern/pages/servers/express.mdx +++ b/fern/pages/servers/express.mdx @@ -1,7 +1,7 @@ --- -title: Express.js -description: -subtite: Generate types and networking logic for your Express server. +title: Express Server +description: Generate Express Node.js server code from an API specification including OpenAPI, Swagger, AsyncAPI, and Fern Definition. +subtite: Generate types and networking logic for your Node.js Express server. slug: express --- @@ -9,14 +9,14 @@ Express is a minimal and flexible Node.js web application framework. It is a pop Fern generates TypeScript types and networking logic for your Express server. This saves you time and adds compile-time safety by guaranteeing that you are serving the exact API that you specified in your API definition. -## What gets generated? +## What Fern generates - TypeScript interfaces for your API types - Exceptions that you can throw for non-200 responses - Interfaces for you to define your business logic - All the networking/HTTP logic to call your API -## Getting started +## Use the starter repository Clone the [starter repo](https://github.com/fern-api/express-starter/) for Express + React. @@ -28,6 +28,16 @@ Learn how Fern can be helpful when building an Express server. ## Getting started + + +### Step 1: Define your API + +Define your API using OpenAPI or the Fern Definition. + +### Step 2: Add the Express generator + +Add the Express server generator to your `generators.yml` file. + ```yaml groups: @@ -41,39 +51,113 @@ groups: ``` -Make sure to enable `allowSyntheticDefaultImports` in your `tsconfig.json` when using this generator. - -## Configurations - -The following options are supported when generating an Express server. +### Step 3: Generate code -### `useBrandedStringAliases` +Run the [CLI](../cli-api/overview.mdx#) command `fern generate --group express-server`. -### `treatUnknownAsAny` - -### `noSerdeLayer` +Make sure to enable `allowSyntheticDefaultImports` in your `tsconfig.json` when using this generator. -### `outputSourceFiles` +### Step 4: Implement the functions -### `areImplementationsOptional` +Provide the business logic by implementing each function. For example, if we were implenting the IMDb API, we would implement the `get_movie` function. -**Type**: boolean ** -Default:** false + +```python +from .generated.fern import AbstractMoviesService, Movie, MovieDoesNotExistError, MovieId -By default, the generated register() will require an implementatiion for every service defined in your Fern Definition. +class MoviesService(AbstractMoviesService): + def get_movie(self, *, movie_id: str) -> Movie: + if movie_id == "titanic": + return Movie( + id=MovieId.from_str("titantic"), + title="Titanic", + rating=9.8, + ) + raise MovieDoesNotExistError(MovieId.from_str(movie_id)) +``` + -If areImplementationsOptional is enabled, then register() won't require any implementations. Note that this is mildly dangerous: if you forget to include an implementation, then your server behavior may drift from your docs and clients. +### Step 5: Run the server -### `doNotHandleUnrecognizedErrors` +```bash +$ poetry run start +``` -**Type**: boolean -**Default**: false +### Step 6: Call the API 🚀 + +```bash +$ curl --location --request GET --silent 'localhost:8080/movies/titanic' | jq . +{ + "id": "titantic", + "title": "Titanic", + "rating": 9.8 +} + +$ curl --location --request GET --silent 'localhost:8080/movies/oceans-11' | jq . +{ + "error": "MovieDoesNotExistError", + "errorInstanceId": "f6e1d69c-bf97-42d5-bc89-5e42773e3880", + "content": "oceans-11" +} +``` -By default, if you throw a non-Fern error in your endpoint handler, it will be caught by generated code and a `500` response will be returned. No details from the error will be leaked to the client. + -If doNotHandleUnrecognizedErrors is enabled and you throw a non-Fern error, the error will be caught and passed on with `next(error)`. It's your responsibility to set up error-catching middleware that handles the error and returns a response to the client. +## Advanced Configurations +Tailor the `config` of the Express server generator to your needs. The default values for all options are `false`. +```yaml + useBrandedStringAliases: + type: boolean + docs: When enabled, string aliases are generated as branded strings. This makes each alias feel like its own type and improves compile-time safety. + areImplementationsOptional: boolean + doNotHandleUnrecognizedErrors: boolean + includeUtilsOnUnionMembers: boolean + includeOtherInUnionTypes: boolean + treatUnknownAsAny: + type: boolean + docs: When enabled, unknown types at runtime are generated into TypeScript using the `any` type. + noSerdeLayer: + type: boolean + docs: | + Allows you to control whether (de-)serialization code is generated. When true, the client uses JSON.parse() and JSON.stringify() instead. + + By default, the generated client includes a layer for serializing requests and deserializing responses. This has three benefits: + + 1. The client validates requests and response at runtime, client-side. + 2. The client can support complex types, like Date and Set. + 3. The generated types can stray from the wire/JSON representation to be more idiomatic. For example, when `noSerdeLayer` is disabled, all properties are camelCase, even if the server is expecting snake_case. + skipRequestValidation: boolean + skipResponseValidation: + type: boolean + docs: By default, this config is set to false and the client will throw an error if the response from the server doesn't match the expected type (based on how the response is modeled in the API definition). Set this config to true to never throw an error if the response is misshapen. Rather, the client will log the issue using console.warn and return the data (cast to the expected response type). + outputEsm: + type: boolean + docs: Allows you to control whether the generated TypeScript targets `CommonJS` or `esnext`. By default, the generated TypeScript targets `CommonJS`. + outputSourceFiles: + type: boolean + docs: When disabled (default), the generator outputs .js and d.ts files. When enabled, the generator outputs raw TypeScript files. + retainOriginalCasing: boolean + allowExtraFields: boolean +``` +The configuration options are accessible in [`ExpressCustomConfig.ts`](https://github.com/fern-api/fern/blob/main/generators/typescript/express/cli/src/custom-config/ExpressCustomConfig.ts). +### Example Configuration + +```diff +groups: + express-server: + generators: + - name: fernapi/fern-typescript-express + version: 0.15.0 + output: + location: local-file-system + path: ../app/server ++ config: ++ useBrandedStringAliases: true ++ noSerdeLayer: true +``` + \ No newline at end of file diff --git a/fern/pages/servers/fastapi.mdx b/fern/pages/servers/fastapi.mdx index e69de29bb2d..cc6017066d4 100644 --- a/fern/pages/servers/fastapi.mdx +++ b/fern/pages/servers/fastapi.mdx @@ -0,0 +1,132 @@ +--- +title: FastAPI Server +description: Generate FastAPI server code from an API specification including OpenAPI, Swagger, AsyncAPI, and Fern Definition. +subtite: Generate types and networking logic for your Python FastAPI server. +slug: fastapi +--- + +FastAPI is a modern, fast web framework for building APIs with Python based on standard Python type hints. It is a popular choice for building APIs and web servers. + +Fern outputs types and networking logic for your FastAPI server. This saves you time and adds compile-time safety by guaranteeing that you are serving the exact API that you specified in your API definition. + +## What Fern generates + +- Pydantic models for your API types +- Exceptions that you can throw for non-200 responses +- Abstract classes for you to define your business logic +- All the networking/HTTP logic to call your API + +## Use the starter repository + +Clone the [starter repo](https://github.com/fern-api/fastapi-starter/) for FastAPI + React. + +## Demo video + +Learn how Fern can be helpful when building a FastAPI server. + + + +## Getting started + + + +### Step 1: Define your API + +Define your API using OpenAPI or the Fern Definition. + +### Step 2: Add the FastAPI generator + +Add the FastAPI server generator to your `generators.yml` file. + + +```yaml +groups: + fastapi-server: + generators: + - name: fernapi/fern-fastapi-server + version: 0.9.3 + output: + location: local-file-system + path: ../app/server +``` + + +### Step 3: Generate code + +Run the [CLI](../cli-api/overview.mdx#) command `fern generate --group fastapi-server`. + +### Step 4: Implement the functions + +Provide the business logic by implementing each function. For example, if we were implenting the IMDb API, we would implement the `get_movie` function. + + +```python +from .generated.fern import AbstractMoviesService, Movie, MovieDoesNotExistError, MovieId + +class MoviesService(AbstractMoviesService): + def get_movie(self, *, movie_id: str) -> Movie: + if movie_id == "titanic": + return Movie( + id=MovieId.from_str("titantic"), + title="Titanic", + rating=9.8, + ) + raise MovieDoesNotExistError(MovieId.from_str(movie_id)) +``` + + +### Step 5: Run the server + +```bash +$ poetry run start +``` + +### Step 6: Call the API 🚀 + +```bash +$ curl --location --request GET --silent 'localhost:8080/movies/titanic' | jq . +{ + "id": "titantic", + "title": "Titanic", + "rating": 9.8 +} + +$ curl --location --request GET --silent 'localhost:8080/movies/oceans-11' | jq . +{ + "error": "MovieDoesNotExistError", + "errorInstanceId": "f6e1d69c-bf97-42d5-bc89-5e42773e3880", + "content": "oceans-11" +} +``` + + + +## Advanced Configurations + +Tailor the `config` of the FastAPI server generator to your needs. The default values for all options are `false`. + +```yaml + include_validators: boolean + skip_formatting: boolean + async_handlers: boolean +``` + +The configuration options are accessible in [`custom_config.py`](https://github.com/fern-api/fern/blob/main/generators/python/src/fern_python/generators/fastapi/custom_config.py). + +### Example Configuration + + +```diff +groups: + fastapi-server: + generators: + - name: fernapi/fern-fastapi-server + version: 0.9.3 + output: + location: local-file-system + path: ../app/server ++ config: ++ include_validators: true ++ skip_formatting: true +``` + \ No newline at end of file diff --git a/fern/pages/servers/introduction.mdx b/fern/pages/servers/introduction.mdx index e69de29bb2d..cf966a8a9c3 100644 --- a/fern/pages/servers/introduction.mdx +++ b/fern/pages/servers/introduction.mdx @@ -0,0 +1,22 @@ +--- +title: What is Server Code Generation? +description: Generate server boilerplate code from an API specification including OpenAPI, Swagger, AsyncAPI, and Fern Definition. +subtite: Generate types and networking logic for your server framework of choice. +slug: server-codegen +--- + +Fern's server-side generators output boilerplate application code that includes models and networking logic. This is intended for API First developers, who write their API definition before building their app. Fern supports generating backend code from an OpenAPI specification or Fern Definition. + +## Supported server frameworks + +- Node.js [Express](./express.mdx) +- Python [FastAPI](./fastapi.mdx) +- Java [Spring Boot](./spring.mdx) + +Want to request a new server framework? [Let us know](https://github.com/fern-api/fern/issues/new?assignees=&labels=&projects=&template=feature-request.md&title=%5BFeature%5D). + +## Why use Fern for server code generation? + +1. **Save time**: generate boilerplate code instead of writing it. +1. **Compile-time safety**: get validation that your endpoints are being served correctly. +1. **Develop API-first**: design your API contract before you start building your app. Pick the best server framework for the job. \ No newline at end of file diff --git a/fern/pages/servers/spring.mdx b/fern/pages/servers/spring.mdx index e69de29bb2d..9a7ae187838 100644 --- a/fern/pages/servers/spring.mdx +++ b/fern/pages/servers/spring.mdx @@ -0,0 +1,123 @@ +--- +title: Spring Server +description: Generate Spring Boot server code from an API specification including OpenAPI, Swagger, AsyncAPI, and Fern Definition. +subtite: Generate types and networking logic for your Java Spring Boot server. +slug: spring +--- + +Spring Boot is a popular Java framework for building APIs and web servers. It is a framework widely used in the Java community. + +Fern outputs types and networking logic for your Spring Boot server. This saves you time and adds compile-time safety by guaranteeing that you are serving the exact API that you specified in your API definition. + +## What Fern generates + +- Java classes for your API types +- Exceptions that you can throw for non-200 responses +- Abstract classes for you to define your business logic +- All the networking/HTTP logic to call your API + +## Use the starter repository + +Clone the [starter repo](https://github.com/fern-api/spring-starter/) for Spring + React. + +## Demo video + +Learn how Fern can be helpful when building a Spring server. + + + +## Getting started + + + +### Step 1: Define your API + +Define your API using OpenAPI or the Fern Definition. + +### Step 2: Add the Spring generator + +Add the Spring server generator to your `generators.yml` file. + + +```yaml +groups: + spring-server: + generators: + - name: fernapi/fern-java-spring + version: 0.8.3 + output: + location: local-file-system + path: ../app/server +``` + + +### Step 3: Generate code + +Run the [CLI](../cli-api/overview.mdx#) command `fern generate --group spring-server`. + +### Step 4: Implement the functions + +Provide the business logic by implementing each function. + +### Step 5: Run the server + +```bash +// if using Maven +$ mvn spring-boot:run + +// if using Gradle +$ gradle bootRun +``` + +### Step 6: Call the API 🚀 + +```bash +$ curl --location --request GET --silent 'localhost:8080/movies/titanic' | jq . +{ + "id": "titantic", + "title": "Titanic", + "rating": 9.8 +} + +$ curl --location --request GET --silent 'localhost:8080/movies/oceans-11' | jq . +{ + "error": "MovieDoesNotExistError", + "errorInstanceId": "f6e1d69c-bf97-42d5-bc89-5e42773e3880", + "content": "oceans-11" +} +``` + + + +## Advanced Configurations + +Tailor the `config` of the Spring Boot server generator to your needs. + +```yaml +wrappedAliases: + type: boolean + default: true +enablePublicConstructors: + type: boolean + default: false +``` + +The configuration options are accessible in [`SpringCustomConfig.java`](https://github.com/fern-api/fern/blob/main/generators/java/spring/src/main/java/com/fern/java/spring/SpringCustomConfig.java). + +### Example Configuration + + +```diff +groups: + spring-server: + generators: + - name: fernapi/fern-java-spring + version: 0.8.3 + output: + location: local-file-system + path: ../app/server ++ config: ++ wrappedAliases: false ++ enablePublicConstructors: true +``` + \ No newline at end of file diff --git a/fern/pages/welcome.mdx b/fern/pages/welcome.mdx index 04876e47d25..83004c7b445 100644 --- a/fern/pages/welcome.mdx +++ b/fern/pages/welcome.mdx @@ -11,13 +11,13 @@ Fern is a developer tool designed to generate SDKs, documentation, and servers f ## Products - + - Design your API before building your app + Idiomatic client libraries A beautiful documentation website - - Idiomatic client libraries - +## Go API First +Fern allows developers to design their API before building their app. This approach is known as `API First Development` and allows teams to iterate on their API design before writing any code. Use Fern to generate server code, SDKs, and documentation from your API definition. +If you're starting from scratch, we recommend you start with the Fern Definition. Think of it as _OpenAPI simple_. +Fern supports the following inputs +- [OpenAPI (formerly Swagger)](./api-definition/openapi/openapi-overview.mdx) +- [Fern Definition](./api-definition/fern-definition/ferndef-overview.mdx) \ No newline at end of file From 581adf7aaea8e2c89631e5c322b9a6de7806efcf Mon Sep 17 00:00:00 2001 From: Catherine Deskur Date: Tue, 4 Jun 2024 10:46:59 -0400 Subject: [PATCH 4/7] remove step text --- fern/pages/servers/express.mdx | 13 ++++++------- fern/pages/servers/fastapi.mdx | 12 ++++++------ fern/pages/servers/spring.mdx | 12 ++++++------ 3 files changed, 18 insertions(+), 19 deletions(-) diff --git a/fern/pages/servers/express.mdx b/fern/pages/servers/express.mdx index ab08c20b6aa..b6bbffa5d89 100644 --- a/fern/pages/servers/express.mdx +++ b/fern/pages/servers/express.mdx @@ -30,11 +30,11 @@ Learn how Fern can be helpful when building an Express server. -### Step 1: Define your API +### Define your API Define your API using OpenAPI or the Fern Definition. -### Step 2: Add the Express generator +### Add the Express generator Add the Express server generator to your `generators.yml` file. @@ -51,13 +51,12 @@ groups: ``` -### Step 3: Generate code - +### Run the [CLI](../cli-api/overview.mdx#) command `fern generate --group express-server`. Make sure to enable `allowSyntheticDefaultImports` in your `tsconfig.json` when using this generator. -### Step 4: Implement the functions +### Implement the functions Provide the business logic by implementing each function. For example, if we were implenting the IMDb API, we would implement the `get_movie` function. @@ -77,13 +76,13 @@ class MoviesService(AbstractMoviesService): ``` -### Step 5: Run the server +### Run the server ```bash $ poetry run start ``` -### Step 6: Call the API 🚀 +### Call the API 🚀 ```bash $ curl --location --request GET --silent 'localhost:8080/movies/titanic' | jq . diff --git a/fern/pages/servers/fastapi.mdx b/fern/pages/servers/fastapi.mdx index cc6017066d4..eead85ffa87 100644 --- a/fern/pages/servers/fastapi.mdx +++ b/fern/pages/servers/fastapi.mdx @@ -30,11 +30,11 @@ Learn how Fern can be helpful when building a FastAPI server. -### Step 1: Define your API +### Define your API Define your API using OpenAPI or the Fern Definition. -### Step 2: Add the FastAPI generator +### Add the FastAPI generator Add the FastAPI server generator to your `generators.yml` file. @@ -51,11 +51,11 @@ groups: ``` -### Step 3: Generate code +### Generate code Run the [CLI](../cli-api/overview.mdx#) command `fern generate --group fastapi-server`. -### Step 4: Implement the functions +### Implement the functions Provide the business logic by implementing each function. For example, if we were implenting the IMDb API, we would implement the `get_movie` function. @@ -75,13 +75,13 @@ class MoviesService(AbstractMoviesService): ``` -### Step 5: Run the server +### Run the server ```bash $ poetry run start ``` -### Step 6: Call the API 🚀 +### Call the API 🚀 ```bash $ curl --location --request GET --silent 'localhost:8080/movies/titanic' | jq . diff --git a/fern/pages/servers/spring.mdx b/fern/pages/servers/spring.mdx index 9a7ae187838..212ec04210f 100644 --- a/fern/pages/servers/spring.mdx +++ b/fern/pages/servers/spring.mdx @@ -30,11 +30,11 @@ Learn how Fern can be helpful when building a Spring server. -### Step 1: Define your API +### Define your API Define your API using OpenAPI or the Fern Definition. -### Step 2: Add the Spring generator +### Add the Spring generator Add the Spring server generator to your `generators.yml` file. @@ -51,15 +51,15 @@ groups: ``` -### Step 3: Generate code +### Generate code Run the [CLI](../cli-api/overview.mdx#) command `fern generate --group spring-server`. -### Step 4: Implement the functions +### Implement the functions Provide the business logic by implementing each function. -### Step 5: Run the server +### Run the server ```bash // if using Maven @@ -69,7 +69,7 @@ $ mvn spring-boot:run $ gradle bootRun ``` -### Step 6: Call the API 🚀 +### Call the API 🚀 ```bash $ curl --location --request GET --silent 'localhost:8080/movies/titanic' | jq . From 7e3a80848b02c8a3ffdd2da14e0a625e6499cf6d Mon Sep 17 00:00:00 2001 From: fern-bot Date: Sun, 25 Aug 2024 13:44:56 -0400 Subject: [PATCH 5/7] update server docs --- fern/docs.yml | 4 +- fern/fern.config.json | 2 +- fern/pages/servers/express.mdx | 57 ++++++++++------------------- fern/pages/servers/fastapi.mdx | 25 +++++++------ fern/pages/servers/introduction.mdx | 6 +-- fern/pages/servers/spring.mdx | 18 ++++----- fern/pages/welcome.mdx | 4 +- 7 files changed, 47 insertions(+), 69 deletions(-) diff --git a/fern/docs.yml b/fern/docs.yml index 8d055c2212d..2b2019c56e4 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -282,12 +282,12 @@ navigation: path: ./pages/servers/introduction.mdx - section: Server Frameworks contents: + - page: Express server + path: ./pages/servers/express.mdx - page: FastAPI server path: ./pages/servers/fastapi.mdx - page: Spring server path: ./pages/servers/spring.mdx - - page: Express server - path: ./pages/servers/express.mdx - tab: cli-api layout: - section: CLI Reference diff --git a/fern/fern.config.json b/fern/fern.config.json index 04b90b8a847..de3dbbf894a 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "fern", - "version": "0.29.0" + "version": "0.39.18" } \ No newline at end of file diff --git a/fern/pages/servers/express.mdx b/fern/pages/servers/express.mdx index b6bbffa5d89..a902782d568 100644 --- a/fern/pages/servers/express.mdx +++ b/fern/pages/servers/express.mdx @@ -24,7 +24,7 @@ Clone the [starter repo](https://github.com/fern-api/express-starter/) for Expre Learn how Fern can be helpful when building an Express server. - +
## Getting started @@ -32,7 +32,7 @@ Learn how Fern can be helpful when building an Express server. ### Define your API -Define your API using OpenAPI or the Fern Definition. +Define your API using the [OpenAPI Specification](/learn/api-definition/openapi/overview) or the [Fern Definition](/learn/api-definition/fern/overview). ### Add the Express generator @@ -52,7 +52,7 @@ groups: ### -Run the [CLI](../cli-api/overview.mdx#) command `fern generate --group express-server`. +Run the [CLI](/learn/cli-api/cli-reference/cli-overview) command `fern generate --group express-server`. Make sure to enable `allowSyntheticDefaultImports` in your `tsconfig.json` when using this generator. @@ -79,7 +79,7 @@ class MoviesService(AbstractMoviesService): ### Run the server ```bash -$ poetry run start +poetry run start ``` ### Call the API 🚀 @@ -106,40 +106,21 @@ $ curl --location --request GET --silent 'localhost:8080/movies/oceans-11' | jq Tailor the `config` of the Express server generator to your needs. The default values for all options are `false`. -```yaml - useBrandedStringAliases: - type: boolean - docs: When enabled, string aliases are generated as branded strings. This makes each alias feel like its own type and improves compile-time safety. - areImplementationsOptional: boolean - doNotHandleUnrecognizedErrors: boolean - includeUtilsOnUnionMembers: boolean - includeOtherInUnionTypes: boolean - treatUnknownAsAny: - type: boolean - docs: When enabled, unknown types at runtime are generated into TypeScript using the `any` type. - noSerdeLayer: - type: boolean - docs: | - Allows you to control whether (de-)serialization code is generated. When true, the client uses JSON.parse() and JSON.stringify() instead. - - By default, the generated client includes a layer for serializing requests and deserializing responses. This has three benefits: - - 1. The client validates requests and response at runtime, client-side. - 2. The client can support complex types, like Date and Set. - 3. The generated types can stray from the wire/JSON representation to be more idiomatic. For example, when `noSerdeLayer` is disabled, all properties are camelCase, even if the server is expecting snake_case. - skipRequestValidation: boolean - skipResponseValidation: - type: boolean - docs: By default, this config is set to false and the client will throw an error if the response from the server doesn't match the expected type (based on how the response is modeled in the API definition). Set this config to true to never throw an error if the response is misshapen. Rather, the client will log the issue using console.warn and return the data (cast to the expected response type). - outputEsm: - type: boolean - docs: Allows you to control whether the generated TypeScript targets `CommonJS` or `esnext`. By default, the generated TypeScript targets `CommonJS`. - outputSourceFiles: - type: boolean - docs: When disabled (default), the generator outputs .js and d.ts files. When enabled, the generator outputs raw TypeScript files. - retainOriginalCasing: boolean - allowExtraFields: boolean -``` +| Configuration Option | Description | +| -------------------- | ----------- | +| `useBrandedStringAliases` | When `true`, string aliases are generated as branded strings. This makes each alias feel like its own type and improves compile-time safety. | +| `areImplementationsOptional` | | +| `doNotHandleUnrecognizedErrors` | | +| `includeUtilsOnUnionMembers` | | +| `includeOtherInUnionTypes` | | +| `treatUnknownAsAny` | When `true`, unknown types at runtime are generated into TypeScript using the `any` type. | +| `noSerdeLayer` | Allows you to control whether (de-)serialization code is generated. When true, the client uses JSON.parse() and JSON.stringify() instead.
By default, the generated client includes a layer for serializing requests and deserializing responses. This has three benefits:
1. The client validates requests and response at runtime, client-side.
2. The client can support complex types, like Date and Set.
3. The generated types can stray from the wire/JSON representation to be more idiomatic. For example, when `noSerdeLayer` is disabled, all properties are camelCase, even if the server is expecting snake_case. | +| `skipRequestValidation` | | +| `skipResponseValidation` | By default, this config is set to `false` and the client will throw an error if the response from the server doesn't match the expected type (based on how the response is modeled in the API definition). Set this config to `true` to never throw an error if the response is misshapen. Rather, the client will log the issue using console.warn and return the data (cast to the expected response type). | +| `outputEsm` | Allows you to control whether the generated TypeScript targets `CommonJS` or `esnext`. By default, the generated TypeScript targets `CommonJS`. | +| `outputSourceFiles` | When `false` (default), the generator outputs .js and d.ts files. When `true`, the generator outputs raw TypeScript files. | +| `retainOriginalCasing` | | +| `allowExtraFields` | | The configuration options are accessible in [`ExpressCustomConfig.ts`](https://github.com/fern-api/fern/blob/main/generators/typescript/express/cli/src/custom-config/ExpressCustomConfig.ts). diff --git a/fern/pages/servers/fastapi.mdx b/fern/pages/servers/fastapi.mdx index eead85ffa87..20cdf5a537b 100644 --- a/fern/pages/servers/fastapi.mdx +++ b/fern/pages/servers/fastapi.mdx @@ -24,7 +24,7 @@ Clone the [starter repo](https://github.com/fern-api/fastapi-starter/) for FastA Learn how Fern can be helpful when building a FastAPI server. - +
## Getting started @@ -32,7 +32,7 @@ Learn how Fern can be helpful when building a FastAPI server. ### Define your API -Define your API using OpenAPI or the Fern Definition. +Define your API using the [OpenAPI Specification](/learn/api-definition/openapi/overview) or the [Fern Definition](/learn/api-definition/fern/overview). ### Add the FastAPI generator @@ -53,7 +53,7 @@ groups: ### Generate code -Run the [CLI](../cli-api/overview.mdx#) command `fern generate --group fastapi-server`. +Run the [CLI](/learn/cli-api/cli-reference/cli-overview) command `fern generate --group fastapi-server`. ### Implement the functions @@ -78,7 +78,7 @@ class MoviesService(AbstractMoviesService): ### Run the server ```bash -$ poetry run start +poetry run start ``` ### Call the API 🚀 @@ -105,11 +105,11 @@ $ curl --location --request GET --silent 'localhost:8080/movies/oceans-11' | jq Tailor the `config` of the FastAPI server generator to your needs. The default values for all options are `false`. -```yaml - include_validators: boolean - skip_formatting: boolean - async_handlers: boolean -``` +| Configuration Option | Description | +| -------------------- | ----------- | +| `include_validators` | | +| `skip_formatting` | | +| `async_handlers` | | The configuration options are accessible in [`custom_config.py`](https://github.com/fern-api/fern/blob/main/generators/python/src/fern_python/generators/fastapi/custom_config.py). @@ -126,7 +126,8 @@ groups: location: local-file-system path: ../app/server + config: -+ include_validators: true -+ skip_formatting: true ++ include_validators: true ++ skip_formatting: true ++ async_handlers: true ``` - \ No newline at end of file + diff --git a/fern/pages/servers/introduction.mdx b/fern/pages/servers/introduction.mdx index cf966a8a9c3..dd57288c48e 100644 --- a/fern/pages/servers/introduction.mdx +++ b/fern/pages/servers/introduction.mdx @@ -9,9 +9,9 @@ Fern's server-side generators output boilerplate application code that includes ## Supported server frameworks -- Node.js [Express](./express.mdx) -- Python [FastAPI](./fastapi.mdx) -- Java [Spring Boot](./spring.mdx) +- Node.js [Express](/learn/express) +- Python [FastAPI](/learn/fastapi) +- Java [Spring Boot](/learn/spring) Want to request a new server framework? [Let us know](https://github.com/fern-api/fern/issues/new?assignees=&labels=&projects=&template=feature-request.md&title=%5BFeature%5D). diff --git a/fern/pages/servers/spring.mdx b/fern/pages/servers/spring.mdx index 212ec04210f..60535914b9d 100644 --- a/fern/pages/servers/spring.mdx +++ b/fern/pages/servers/spring.mdx @@ -24,7 +24,7 @@ Clone the [starter repo](https://github.com/fern-api/spring-starter/) for Spring Learn how Fern can be helpful when building a Spring server. - +
## Getting started @@ -32,7 +32,7 @@ Learn how Fern can be helpful when building a Spring server. ### Define your API -Define your API using OpenAPI or the Fern Definition. +Define your API using the [OpenAPI Specification](/learn/api-definition/openapi/overview) or the [Fern Definition](/learn/api-definition/fern/overview). ### Add the Spring generator @@ -53,7 +53,7 @@ groups: ### Generate code -Run the [CLI](../cli-api/overview.mdx#) command `fern generate --group spring-server`. +Run the [CLI](/learn/cli-api/cli-reference/cli-overview) command `fern generate --group spring-server`. ### Implement the functions @@ -93,14 +93,10 @@ $ curl --location --request GET --silent 'localhost:8080/movies/oceans-11' | jq Tailor the `config` of the Spring Boot server generator to your needs. -```yaml -wrappedAliases: - type: boolean - default: true -enablePublicConstructors: - type: boolean - default: false -``` +| Configuration Option | Description | +| -------------------- | ----------- | +| `wrappedAliases`| | +| `enablePublicConstructors` | | The configuration options are accessible in [`SpringCustomConfig.java`](https://github.com/fern-api/fern/blob/main/generators/java/spring/src/main/java/com/fern/java/spring/SpringCustomConfig.java). diff --git a/fern/pages/welcome.mdx b/fern/pages/welcome.mdx index 83004c7b445..bd7c2210883 100644 --- a/fern/pages/welcome.mdx +++ b/fern/pages/welcome.mdx @@ -61,5 +61,5 @@ Fern allows developers to design their API before building their app. This appro If you're starting from scratch, we recommend you start with the Fern Definition. Think of it as _OpenAPI simple_. Fern supports the following inputs -- [OpenAPI (formerly Swagger)](./api-definition/openapi/openapi-overview.mdx) -- [Fern Definition](./api-definition/fern-definition/ferndef-overview.mdx) \ No newline at end of file +- [OpenAPI (formerly Swagger)](/learn/api-definition/openapi/overview) +- [Fern Definition](/learn/api-definition/fern/overview) \ No newline at end of file From 7de679ab0858e42c791d2da1bc3043cea684b4ec Mon Sep 17 00:00:00 2001 From: Danny Sheridan <83524670+dannysheridan@users.noreply.github.com> Date: Mon, 26 Aug 2024 18:50:48 -0400 Subject: [PATCH 6/7] Update welcome.mdx --- fern/pages/welcome.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/pages/welcome.mdx b/fern/pages/welcome.mdx index a9e7d4a4727..46c32144026 100644 --- a/fern/pages/welcome.mdx +++ b/fern/pages/welcome.mdx @@ -30,7 +30,7 @@ Fern is a developer tool designed to generate SDKs, documentation, and servers f A beautiful documentation website @@ -65,4 +65,4 @@ Fern allows developers to design their API before building their app. This appro Fern supports the following inputs - [OpenAPI (formerly Swagger)](/learn/api-definition/openapi/overview) -- [Fern Definition](/learn/api-definition/fern/overview) \ No newline at end of file +- [Fern Definition](/learn/api-definition/fern/overview) From 4a1ab50be0639a38757b3ff0a17a59130977cfdd Mon Sep 17 00:00:00 2001 From: Danny Sheridan <83524670+dannysheridan@users.noreply.github.com> Date: Mon, 26 Aug 2024 18:52:15 -0400 Subject: [PATCH 7/7] Update docs.yml --- fern/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/docs.yml b/fern/docs.yml index 147fcf5fd25..94eb4da7e3c 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -28,7 +28,7 @@ tabs: display-name: SDKs slug: sdks servers: - display-name: Servers + display-name: Server Stubs slug: servers cli-api: display-name: CLI & API Reference