Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: define fern as a toolkit #2974

Merged
merged 2 commits into from
Feb 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 37 additions & 35 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

</div>

Fern is an open-source toolkit that allows you to effortlessly generate SDKs and API documentation.
Fern is a toolkit that allows you to effortlessly generate SDKs and API documentation.

<div align="center">
<img src="/fern/docs/images/overview.png" width="700" alt="Overview Diagram">
Expand All @@ -31,15 +31,15 @@ The Fern toolkit is available as a command line interface (CLI). To install it,
npm install -g fern-api
```

Initialize Fern with your OpenAPI spec:
Initialize Fern with your OpenAPI spec:

```bash
fern init --openapi ./path/to/openapi.yml
# or
fern init --openapi https://petstore.swagger.io/v2/swagger.json
```

Your directory should look like the following:
Your directory should look like the following:

```yaml
fern/
Expand Down Expand Up @@ -67,11 +67,11 @@ Check out docs built with Fern:
- [docs.superagent.sh](https://docs.superagent.sh/)
- [docs.propexo.com](https://docs.propexo.com/)

Get started [here](https://github.com/fern-api/docs-starter).
Get started [here](https://github.com/fern-api/docs-starter).

## 🌿 Generators

Generators are process that take your API Definition as input and output artifacts (SDKs,
Generators are process that take your API Definition as input and output artifacts (SDKs,
Postman Collections, Server boilerplate, etc.). To add a generator run `fern add <generator id>`

### SDK Generators
Expand All @@ -86,35 +86,35 @@ Postman Collections, Server boilerplate, etc.). To add a generator run `fern add

### Server-side Generators

Fern's server-side generators output boilerplate application code (models and networking logic). This is intended for spec-first or API-first developers,
who write their API definition (as an OpenAPI spec or Fern definition) and want to geenerate backend code. Watch a demo [here](https://docs.buildwithfern.com/server-boilerplate/server-boilerplate/express-js#demo-video).
Fern's server-side generators output boilerplate application code (models and networking logic). This is intended for spec-first or API-first developers,
who write their API definition (as an OpenAPI spec or Fern definition) and want to geenerate backend code. Watch a demo [here](https://docs.buildwithfern.com/server-boilerplate/server-boilerplate/express-js#demo-video).

| Generator ID | Latest Version | Changelog | Entrypoint |
| -------------------------------------- | -------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `fernapi/fern-express-server` | `0.9.7` | [CHANGELOG.md](./generators/typescript/express/CHANGELOG.md) | [cli.ts](./generators/typescript/express/cli/src/cli.ts) |
| `fernapi/fern-fastapi-server` | `0.7.7` | [CHANGELOG.md](./generators/python/fastapi/CHANGELOG.md) | [cli.py](./generators/python/src/fern_python/generators/sdk/cli.py) |
| `fernapi/fern-java-spring` | `0.7.1` | [CHANGELOG.md](./generators/java/spring/CHANGELOG.md) | [Cli.java](./generators/java/spring/src/main/java/com/fern/java/spring/Cli.java)|
| Generator ID | Latest Version | Changelog | Entrypoint |
| ----------------------------- | -------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| `fernapi/fern-express-server` | `0.9.7` | [CHANGELOG.md](./generators/typescript/express/CHANGELOG.md) | [cli.ts](./generators/typescript/express/cli/src/cli.ts) |
| `fernapi/fern-fastapi-server` | `0.7.7` | [CHANGELOG.md](./generators/python/fastapi/CHANGELOG.md) | [cli.py](./generators/python/src/fern_python/generators/sdk/cli.py) |
| `fernapi/fern-java-spring` | `0.7.1` | [CHANGELOG.md](./generators/java/spring/CHANGELOG.md) | [Cli.java](./generators/java/spring/src/main/java/com/fern/java/spring/Cli.java) |

### Model Generators

Fern's model generators will output schemas or types defined in your OpenAPI spec or Fern Definition.
Fern's model generators will output schemas or types defined in your OpenAPI spec or Fern Definition.

| Generator ID | Latest Version | Changelog | Entrypoint |
| -------------------------------------- | -------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `fernapi/fern-pydantic-model` | `0.8.0` | [CHANGELOG.md](./generators/python/pydantic/CHANGELOG.md) | [cli.py](./generators/python/src/fern_python/generators/sdk/cli.py) |
| `fernapi/fern-java-model` | `0.7.1` | [CHANGELOG.md](./generators/java/sdk/CHANGELOG.md) | [Cli.java](./generators/java/sdk/src/main/java/com/fern/java/client/Cli.java) |
| `fernapi/fern-ruby-model` | `0.0.6` | [CHANGELOG.md](./generators/ruby/model/CHANGELOG.md) | [cli.ts](./generators/ruby/model/src/cli.ts) |
| Generator ID | Latest Version | Changelog | Entrypoint |
| ----------------------------- | -------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `fernapi/fern-pydantic-model` | `0.8.0` | [CHANGELOG.md](./generators/python/pydantic/CHANGELOG.md) | [cli.py](./generators/python/src/fern_python/generators/sdk/cli.py) |
| `fernapi/fern-java-model` | `0.7.1` | [CHANGELOG.md](./generators/java/sdk/CHANGELOG.md) | [Cli.java](./generators/java/sdk/src/main/java/com/fern/java/client/Cli.java) |
| `fernapi/fern-ruby-model` | `0.0.6` | [CHANGELOG.md](./generators/ruby/model/CHANGELOG.md) | [cli.ts](./generators/ruby/model/src/cli.ts) |

### Spec Generators

Fern's spec generators can output an OpenAPI spec or a Postman collection.
Fern's spec generators can output an OpenAPI spec or a Postman collection.

> **Note**: The OpenAPI spec generator is primarly intended for Fern Definition users. This prevents lock-in so that one can always export to OpenAPI.
> **Note**: The OpenAPI spec generator is primarly intended for Fern Definition users. This prevents lock-in so that one can always export to OpenAPI.

| Generator ID | Latest Version | Changelog | Entrypoint |
| -------------------------------------- | -------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `fernapi/fern-openapi` | `0.0.30` | [CHANGELOG.md](./generators/openapi/CHANGELOG.md) | [cli.ts](./generators/openapi/src/cli.ts) |
| `fernapi/fern-postman` | `0.1.0` | [CHANGELOG.md](./generators/postman/CHANGELOG.md) | [cli.ts](./generators/postman//src/cli.ts) |
| Generator ID | Latest Version | Changelog | Entrypoint |
| ---------------------- | -------------- | ------------------------------------------------- | ------------------------------------------ |
| `fernapi/fern-openapi` | `0.0.30` | [CHANGELOG.md](./generators/openapi/CHANGELOG.md) | [cli.ts](./generators/openapi/src/cli.ts) |
| `fernapi/fern-postman` | `0.1.0` | [CHANGELOG.md](./generators/postman/CHANGELOG.md) | [cli.ts](./generators/postman//src/cli.ts) |

## 🌿 CLI Commands

Expand All @@ -130,16 +130,17 @@ Here's a quick look at the most popular CLI commands. View the documentation for

`fern add <generator>`: include a new generator in your `generators.yml`. For example, `fern add fern-python-sdk`.

## Advanced
## Advanced

### API First
### API First

Fern supports developers and teams that want to be API-first or Spec-first.
Fern supports developers and teams that want to be API-first or Spec-first.

Define your API, and use Fern to generate models, networking code and boilerplate application code. The generated code adds
Define your API, and use Fern to generate models, networking code and boilerplate application code. The generated code adds
type safety to your API implementation - if your backend doesn't implement the API correctly, it won't compile.

Frameworks currently supported:

- [Express](./generators/typescript)
- [Spring Boot](./generators/java)
- [FastAPI](./generators/python)
Expand All @@ -148,10 +149,10 @@ For a walkthrough, check out the [Fern + Express video](https://docs.buildwithfe

### Fern Definition

While we are big fans of OpenAPI, we know it isn't the *easiest* format to read and write. If you're looking for an alternative,
give the Fern Definition a try.
While we are big fans of OpenAPI, we know it isn't the _easiest_ format to read and write. If you're looking for an alternative,
give the Fern Definition a try.

Install the Fern CLI and initialize a Fern Project.
Install the Fern CLI and initialize a Fern Project.

```bash
npm install -g fern-api
Expand Down Expand Up @@ -214,10 +215,11 @@ errors:
type: MovieId
```

Checkout open source projects that are using Fern Definitions:
- [Metriport](https://github.com/metriport/metriport/tree/develop/fern/definition)
- [Rivet](https://github.com/rivet-gg/rivet/tree/main/fern/definition)
- [Revert](https://github.com/revertinc/revert/tree/main/fern/definition)
Checkout open source projects that are using Fern Definitions:

- [Metriport](https://github.com/metriport/metriport/tree/develop/fern/definition)
- [Rivet](https://github.com/rivet-gg/rivet/tree/main/fern/definition)
- [Revert](https://github.com/revertinc/revert/tree/main/fern/definition)

## Community

Expand Down
4 changes: 1 addition & 3 deletions fern/docs/pages/welcome/introduction.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
Fern is an [open source](https://github.com/fern-api/fern) toolkit for building
REST APIs. With Fern, you can generate SDKs, API documentation,
and boilerplate for your backend server.
Fern is a toolkit for building REST APIs. With Fern, you can generate SDKs, API documentation, and boilerplate for your backend server.

Fern is **fully compatible with OpenAPI**. Leverage your existing OpenAPI
specification to generate code and documentation through Fern. If you're not a fan of
Expand Down
2 changes: 1 addition & 1 deletion generators/go/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Fern handles transforming an API definition -- either an OpenAPI or Fern specifi

## What is Fern?

Fern is an open source toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.
Fern is a toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.

Head over to the [official Fern website](https://www.buildwithfern.com/?utm_source=github&utm_medium=readme&utm_campaign=fern-go&utm_content=homepage) for more information, or head over to our [Documentation](https://www.buildwithfern.com/docs/intro?utm_source=github&utm_medium=readme&utm_campaign=fern-go&utm_content=documentation) to dive straight in and find out what Fern can do for you!

Expand Down
8 changes: 4 additions & 4 deletions generators/java/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Java Generator

This repository contains the source for the [Fern]([https://buildwithfern.com](https://www.buildwithfern.com/?utm_source=github&utm_medium=readme&utm_campaign=fern-java&utm_content=repo-contains)) generators that produce Java artifacts:
This repository contains the source for the [Fern](<[https://buildwithfern.com](https://www.buildwithfern.com/?utm_source=github&utm_medium=readme&utm_campaign=fern-java&utm_content=repo-contains)>) generators that produce Java artifacts:

- `fernapi/fern-java-sdk`
- `fernapi/fern-java-model`
Expand All @@ -12,7 +12,7 @@ Fern handles transforming an API definition -- either an OpenAPI or Fern specifi

## What is Fern?

Fern is an open source toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.
Fern is a toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.

Head over to the [official Fern website](https://www.buildwithfern.com/?utm_source=github&utm_medium=readme&utm_campaign=fern-java&utm_content=homepage) for more information, or head over to our [Documentation](https://www.buildwithfern.com/docs/intro?utm_source=github&utm_medium=readme&utm_campaign=fern-java&utm_content=documentation) to dive straight in and find out what Fern can do for you!

Expand Down Expand Up @@ -97,13 +97,13 @@ When enabled, generates public constructors for model types.
**Type:** string

```yaml
custom-dependencies:
custom-dependencies:
- "implementation com.foo:bar:0.0.0"
- "testImplementation com.foo:bar:0.0.0"
- "api com.foo:bar:0.0.0"
```

The provided string will be used as the client class name.
The provided string will be used as the client class name.

## Versions

Expand Down
2 changes: 1 addition & 1 deletion generators/openapi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Fern handles transforming a Fern specification into Fern _intermediate represent

## What is Fern?

Fern is an open source toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.
Fern is a toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.

Head over to the [official Fern website](https://www.buildwithfern.com/?utm_source=github&utm_medium=readme&utm_campaign=fern-openapi&utm_content=homepage) for more information, or head over to our [Documentation](https://www.buildwithfern.com/docs/intro?utm_source=github&utm_medium=readme&utm_campaign=fern-openapi&utm_content=documentation) to dive straight in and find out what Fern can do for you!

Expand Down
2 changes: 1 addition & 1 deletion generators/postman/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Fern handles transforming an API definition -- either an OpenAPI or Fern specifi

## What is Fern?

Fern is an open source toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.
Fern is a toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.

Head over to the [official Fern website](https://www.buildwithfern.com/?utm_source=github&utm_medium=readme&utm_campaign=fern-postman&utm_content=homepage) for more information, or head over to our [Documentation](https://www.buildwithfern.com/docs/intro?utm_source=github&utm_medium=readme&utm_campaign=fern-postman&utm_content=documentation) to dive straight in and find out what Fern can do for you!

Expand Down
3 changes: 1 addition & 2 deletions generators/python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Fern handles transforming an API definition -- either an OpenAPI or Fern specifi

## What is Fern?

Fern is an open source toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.
Fern is a toolkit for designing, building, and consuming REST APIs. With Fern, you can generate client libraries, API documentation, and boilerplate for your backend server.

Head over to the [official Fern website](https://www.buildwithfern.com/?utm_source=github&utm_medium=readme&utm_campaign=fern-python&utm_content=homepage) for more information, or head over to our [Documentation](https://www.buildwithfern.com/docs/intro?utm_source=github&utm_medium=readme&utm_campaign=fern-python&utm_content=documentation) to dive straight in and find out what Fern can do for you!

Expand Down Expand Up @@ -197,7 +197,6 @@ When enabled, all generated services will leverage async endpoint handlers, allo

**Default:** `true`


### Pydantic Generator Configuration

The Pydantic generator supports the following options:
Expand Down
Loading