diff --git a/README.md b/README.md index e80b73b..9b16929 100644 --- a/README.md +++ b/README.md @@ -10,28 +10,10 @@ Create beautiful documentation in under 5 minutes using an OpenAPI/Swagger specification. Here's [an example!](https://petstore-openapi.docs.buildwithfern.com) -[![Discord](https://img.shields.io/badge/Join%20Our%20Community-black?logo=discord)](https://discord.com/invite/JkkXumPzcG) - --- -## Customer Showcase - -Your docs can look this good: - -- [Flatfile's API Reference](https://reference.flatfile.com/api-reference/events/create-an-event) -- [Sugeragent's Docs](https://docs.superagent.sh/) -- [Credal's Docs](https://docs.credal.ai/) - ---- - -## Let's get started - -### About OpenAPI/Swagger - -The OpenAPI specification is a format for describing REST APIs. The specification consists of a single JSON or YAML file. OpenAPI was previously known as Swagger. Fern supports both OpenAPI (3.x) and Swagger (2.x). We'll refer to the specification as OpenAPI throughout this guide. - ### Step 1: Use this template 1. Click on the "Use this template" button. You must be logged into GitHub. @@ -71,59 +53,57 @@ npm install -g fern-api As this is a global command, you can run it from any location. The CLI commands in the following steps must be run from within your repository. -### Step 5: (Optional) Use your OpenAPI specification +### Step 5: Check that your OpenAPI specification is valid -If you'd like to use the an example OpenAPI specificaton file, run: +Run the following command to check that your OpenAPI specification is valid: ```bash -fern init --openapi https://petstore3.swagger.io/api/v3/openapi.json +fern check ``` -If you'd like to use your own OpenAPI specification file, run: +### Step 6: Generate your documentation + +Run the following command: ```bash -fern init --openapi URL_OR_PATH_TO_YOUR_OPENAPI_SPEC +fern generate --docs ``` -You can use a URL to an OAS file online, or you can use a local path. The file must be formatted as JSON or YAML. - -Examples: +You will be prompted to log in and connect your GitHub account. -```fern init --openapi https://petstore3.swagger.io/api/v3/openapi.json``` +Once the documentation is generated, you will receive a URL where your documentation is published. For example: -```fern init --openapi ../apis/openapi.yml``` +```shell +┌─ +│ ✓ petstore-openapi.docs.buildwithfern.com +└─ +``` -Confirm that you see a new folder named `openapi` and that it contains the OAS file you specified, in YAML format. +### Step 7: (Optional) Add your own OpenAPI specification file -*Note: Don't have an OpenAPI spec? Use Fern's simpler format to define your API.* [*Learn more*](https://github.com/fern-api/docs-starter-fern-definition) +If you'd like to use your own OpenAPI file, run: -### Step 6: Check that your OpenAPI specification is valid +```bash +fern init --openapi URL_TO_YOUR_OPENAPI -Run the following command to check that your OpenAPI specification is valid: +# OR -```bash -fern check +fern init --openapi PATH_TO_YOUR_OPENAPI ``` -If you see errors, resolve them in your OpenAPI specification file. If you need help, reach out in [Discord](https://discord.com/invite/JkkXumPzcG) or [via email](mailto:support@buildwithfern.com). We're here to help! +Examples: -### Step 7: Generate your documentation +```bash +fern init --openapi https://raw.githubusercontent.com/fern-api/docs-starter-openapi/main/fern/openapi/openapi.yaml -Generate and publish your documentation with the following command: +# OR -```bash -fern generate --docs +fern init --openapi ../apis/openapi.yml ``` -You will be prompted to log in and connect your GitHub account. - -Once the documentation is generated, you will receive a URL where your documentation is published. For example: +Confirm that you see a folder named `openapi` which contains the OpenAPI file you specified, in YAML format. -```shell -┌─ -│ ✓ petstore-openapi.docs.buildwithfern.com -└─ -``` +*Note: Don't have an OpenAPI spec? Use Fern's simpler format to define your API.* [*Learn more*](https://github.com/fern-api/docs-starter-fern-definition) ### Step 8: Customize your documentation @@ -151,3 +131,21 @@ If you wish to use a custom subdomain like `https://docs.YOUR_ORGANIZATION.com` For advanced documentation features and options, view the full [configuration docs](https://docs.buildwithfern.com/generate-docs/overview/configuration). Good luck creating beautiful and functional documentation! 🌿 + +--- + +### Support + +Need help? Email us at (support@buildwithfern.com)[mailto:support@buildwithfern.com] or join our [Discord community](https://discord.com/invite/JkkXumPzcG). + +### Customer Showcase + +Your docs can look this good: + +- [Flatfile's API Reference](https://reference.flatfile.com/api-reference/events/create-an-event) +- [Sugeragent's Docs](https://docs.superagent.sh/) +- [Credal's Docs](https://docs.credal.ai/) + +### About OpenAPI (formerly Swagger) + +The OpenAPI specification is a format for describing REST APIs. The specification consists of a single JSON or YAML file. OpenAPI was previously known as Swagger. Fern supports both OpenAPI (3.x) and Swagger (2.x). We'll refer to the specification as OpenAPI throughout this guide. \ No newline at end of file diff --git a/fern/docs.yml b/fern/docs.yml index 8e74617..aa78598 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -6,6 +6,8 @@ navigation: contents: - page: Welcome path: ./docs/pages/welcome.mdx + - page: Concepts + path: ./docs/pages/concepts.mdx - page: SDKs path: ./docs/pages/sdks.mdx slug: sdks @@ -13,20 +15,20 @@ navigation: navbar-links: - type: secondary - text: Contact us + text: Get support url: "mailto:support@buildwithfern.com" - type: primary - text: Join the Discord - url: https://discord.com/invite/JkkXumPzcG + text: Get a Demo + url: https://buildwithfern.com/contact colors: accentPrimary: dark: "#f0c193" - light: "#af5f1b." + light: "#af5f1b" logo: dark: ./docs/assets/logo-dark-mode.png light: ./docs/assets/logo-light-mode.png - height: 100 + height: 180 favicon: ./docs/assets/favicon.png diff --git a/fern/docs/pages/concepts.mdx b/fern/docs/pages/concepts.mdx new file mode 100644 index 0000000..0c8cec6 --- /dev/null +++ b/fern/docs/pages/concepts.mdx @@ -0,0 +1,5 @@ +--- +title: Petstore Docs | Concepts +description: Learn about the key concepts of the Petstore API. +--- + diff --git a/fern/docs/pages/sdks.mdx b/fern/docs/pages/sdks.mdx index 6710d2a..d236825 100644 --- a/fern/docs/pages/sdks.mdx +++ b/fern/docs/pages/sdks.mdx @@ -1,5 +1,5 @@ --- -title: Fern Docs | SDKs +title: Petstore | SDKs description: We offer client libraries/SDKs for your favorite languages, generated by Fern from your OpenAPI specification file. --- diff --git a/fern/docs/pages/welcome.mdx b/fern/docs/pages/welcome.mdx index 908dab9..3f3fe19 100644 --- a/fern/docs/pages/welcome.mdx +++ b/fern/docs/pages/welcome.mdx @@ -1,17 +1,13 @@ --- -title: Fern Docs | Welcome to our documentation +title: Pet Store | Welcome to our documentation description: Here you'll find information to get started, as well as a sample API Reference generated by Fern from an OpenAPI specification file. --- - -Start building beautiful documentation in under 5 minutes. - +Welcome to the Pet Store API docs! This site demonstrates how to use Fern to generate API documentation from an OpenAPI specification file. You can [use this site template](https://github.com/fern-api/docs-starter-openapi) as a starting point for your own API documentation. -## Introduction +## Getting Started -Welcome to the Petstore Sample API docs! Here you'll find information about managing your pets, customers, and orders for your pet shop. - -## Frequently Visited Resources +Here you'll find information about managing your pets, customers, and orders for your pet shop. - +
@@ -41,10 +37,4 @@ Welcome to the Petstore Sample API docs! Here you'll find information about mana ## Get support -We have three channels to assist: - -1. Post in the [Discord Community](https://discord.com/invite/JkkXumPzcG) where you can get help from Fern engineers and community members. - -2. Open an issue on [GitHub](https://github.com/fern-api/docs-starter-openapi/issues/new) and we'll get back to you promptly. - -3. Email us at [support@buildwithfern.com](mailto:support@buildwithfern.com) and we'll do our best to reply within 24 hours. +Want to get in touch with the Fern team? Open an issue on [GitHub](https://github.com/fern-api/docs-starter-openapi/issues/new) or reach out to us via [email](mailto:support@buildwithfern.com). We're here to help! \ No newline at end of file