From daf2e0c6150580808c4bb3f9967bec42dcb2a6db Mon Sep 17 00:00:00 2001 From: Danny Sheridan Date: Wed, 14 Feb 2024 00:58:03 -0500 Subject: [PATCH] docs: define fern as a toolkit --- README.md | 86 ++++++++++++------------ fern/docs/pages/welcome/introduction.mdx | 4 +- generators/go/README.md | 2 +- generators/java/README.md | 8 +-- generators/openapi/README.md | 2 +- generators/postman/README.md | 2 +- generators/python/README.md | 3 +- 7 files changed, 53 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index da78de25984..f123fc09523 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ -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.
Overview Diagram @@ -31,7 +31,7 @@ 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 @@ -39,7 +39,7 @@ fern init --openapi ./path/to/openapi.yml 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/ @@ -67,54 +67,54 @@ 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 ` ### SDK Generators -| Generator ID | Latest Version | Changelog | Entrypoint | -| -------------------------------------- | -------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------- | -| `fernapi/fern-typescript-node-sdk` | `0.10.0` | [CHANGELOG.md](./generators/typescript/sdk/CHANGELOG.md) | [cli.ts](./generators/typescript/sdk/cli/src/nodeCli.ts) | -| `fernapi/fern-python-sdk` | `0.9.0` | [CHANGELOG.md](./generators/python/pydantic/CHANGELOG.md) | [cli.py](./generators/python/src/fern_python/generators/sdk/cli.py) | -| `fernapi/fern-java-sdk` | `0.8.0` | [CHANGELOG.md](./generators/java/sdk/CHANGELOG.md) | [Cli.java](./generators/java/sdk/src/main/java/com/fern/java/client/Cli.java) | -| `fernapi/fern-ruby-sdk` | `0.0.6` | [CHANGELOG.md](./generators/ruby/sdk/CHANGELOG.md) | [cli.ts](./generators/ruby/sdk/src/cli.ts) | -| `fernapi/fern-go-sdk` | `0.16.0` | [CHANGELOG.md](./generators/go/sdk/CHANGELOG.md) | [main.go](./generators/go/cmd/fern-go-sdk/main.go) | +| Generator ID | Latest Version | Changelog | Entrypoint | +| ---------------------------------- | -------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- | +| `fernapi/fern-typescript-node-sdk` | `0.10.0` | [CHANGELOG.md](./generators/typescript/sdk/CHANGELOG.md) | [cli.ts](./generators/typescript/sdk/cli/src/nodeCli.ts) | +| `fernapi/fern-python-sdk` | `0.9.0` | [CHANGELOG.md](./generators/python/pydantic/CHANGELOG.md) | [cli.py](./generators/python/src/fern_python/generators/sdk/cli.py) | +| `fernapi/fern-java-sdk` | `0.8.0` | [CHANGELOG.md](./generators/java/sdk/CHANGELOG.md) | [Cli.java](./generators/java/sdk/src/main/java/com/fern/java/client/Cli.java) | +| `fernapi/fern-ruby-sdk` | `0.0.6` | [CHANGELOG.md](./generators/ruby/sdk/CHANGELOG.md) | [cli.ts](./generators/ruby/sdk/src/cli.ts) | +| `fernapi/fern-go-sdk` | `0.16.0` | [CHANGELOG.md](./generators/go/sdk/CHANGELOG.md) | [main.go](./generators/go/cmd/fern-go-sdk/main.go) | ### 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 @@ -130,16 +130,17 @@ Here's a quick look at the most popular CLI commands. View the documentation for `fern add `: 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) @@ -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 @@ -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 diff --git a/fern/docs/pages/welcome/introduction.mdx b/fern/docs/pages/welcome/introduction.mdx index de35614c174..11ebad38ee0 100644 --- a/fern/docs/pages/welcome/introduction.mdx +++ b/fern/docs/pages/welcome/introduction.mdx @@ -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 diff --git a/generators/go/README.md b/generators/go/README.md index b230b377b1f..05640e72331 100644 --- a/generators/go/README.md +++ b/generators/go/README.md @@ -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! diff --git a/generators/java/README.md b/generators/java/README.md index 12f066fa0b6..33752266777 100644 --- a/generators/java/README.md +++ b/generators/java/README.md @@ -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` @@ -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! @@ -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 diff --git a/generators/openapi/README.md b/generators/openapi/README.md index d14936965f2..e61d10dfe34 100644 --- a/generators/openapi/README.md +++ b/generators/openapi/README.md @@ -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! diff --git a/generators/postman/README.md b/generators/postman/README.md index e26408bfaf7..3af4673160f 100644 --- a/generators/postman/README.md +++ b/generators/postman/README.md @@ -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! diff --git a/generators/python/README.md b/generators/python/README.md index 0b805ab0b4b..45eb432746c 100644 --- a/generators/python/README.md +++ b/generators/python/README.md @@ -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! @@ -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: