Skip to content

Commit 60b01b8

Browse files
authored
Initial commit
0 parents  commit 60b01b8

File tree

13 files changed

+1251
-0
lines changed

13 files changed

+1251
-0
lines changed

.github/workflows/check.yml

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: fern-check
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
9+
jobs:
10+
run:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout repository
14+
uses: actions/checkout@v4
15+
16+
- name: Install Fern
17+
run: npm install -g fern-api
18+
19+
- name: Check API is valid
20+
run: fern check

.github/workflows/generate-sdks.yml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: generate-sdks
2+
3+
on:
4+
push:
5+
tags:
6+
- "*"
7+
8+
jobs:
9+
run:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout repository
13+
uses: actions/checkout@v4
14+
15+
- name: Install Fern
16+
run: npm install -g fern-api
17+
18+
- name: Generate SDKs
19+
env:
20+
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
21+
run: |
22+
fern generate --group publish --log-level debug --version ${{ github.ref_name }}

.github/workflows/preview-docs.yml

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: preview-docs
2+
3+
on: pull_request
4+
5+
jobs:
6+
run:
7+
runs-on: ubuntu-latest
8+
permissions: write-all
9+
steps:
10+
- name: Checkout repository
11+
uses: actions/checkout@v4
12+
13+
- name: Install Fern
14+
run: npm install -g fern-api
15+
16+
- name: Generate preview URL
17+
id: generate-docs
18+
env:
19+
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
20+
run: |
21+
OUTPUT=$(fern generate --docs --preview 2>&1) || true
22+
echo "$OUTPUT"
23+
URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
24+
echo "Preview URL: $URL"
25+
echo "🌿 Preview your docs: $URL" > preview_url.txt
26+
27+
- name: Comment URL in PR
28+
uses: thollander/[email protected]
29+
with:
30+
filePath: preview_url.txt

.github/workflows/publish-docs.yml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: publish-docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
run:
10+
runs-on: ubuntu-latest
11+
if: github.event_name == 'push' && contains(github.ref, 'refs/heads/main')
12+
steps:
13+
- name: Checkout repository
14+
uses: actions/checkout@v4
15+
16+
- name: Install Fern
17+
run: npm install -g fern-api
18+
19+
- name: Publish Docs
20+
env:
21+
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
22+
run: fern generate --docs --log-level debug

README.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
<br/>
2+
<div align="center">
3+
<a href="https://www.buildwithfern.com/?utm_source=github&utm_medium=readme&utm_campaign=docs-starter-openapi&utm_content=logo">
4+
<img src="/fern/docs/assets/logo_light_mode.png" height="50" align="center" alt="header" />
5+
</a>
6+
7+
<br/>
8+
9+
# Docs Starter
10+
11+
Create beautiful documentation in under 5 minutes using an OpenAPI/Swagger specification. Here's [an example!](https://petstore-openapi.docs.buildwithfern.com)
12+
13+
[![Discord](https://img.shields.io/badge/Join%20Our%20Community-black?logo=discord)](https://discord.com/invite/JkkXumPzcG)
14+
15+
</div>
16+
17+
---
18+
19+
## Customer Showcase
20+
21+
Your docs can look this good:
22+
23+
- [Flatfile's API Reference](https://reference.flatfile.com/api-reference/events/create-an-event)
24+
- [Sugeragent's Docs](https://docs.superagent.sh/)
25+
- [Credal's Docs](https://docs.credal.ai/)
26+
27+
---
28+
29+
## Let's get started
30+
31+
### About OpenAPI/Swagger
32+
33+
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.
34+
35+
### Step 1: Use this template
36+
37+
1. Click on the "Use this template" button. You must be logged into GitHub.
38+
2. Create a new repository. Name it anything you like; `docs` is a common naming choice.
39+
40+
### Step 2: Clone and open in your preferred code editor
41+
42+
Clone your newly created repository and open it in your favorite integrated development environment (IDE) or code editor.
43+
44+
The files and folders discussed in the following steps will be inside a `fern` folder in your repository.
45+
46+
### Step 3: Customize organization name
47+
48+
In the `fern.config.json` file, replace the placeholder organization name with your actual organization name. For example:
49+
50+
```json
51+
{
52+
"organization": "Petstore",
53+
"version": "0.17.2"
54+
}
55+
```
56+
57+
In the `docs.yml` file, update the docs URL to match your organization's naming convention. For example:
58+
59+
```yml
60+
instances:
61+
- url: petstore-openapi.docs.buildwithfern.com
62+
```
63+
64+
### Step 4: Install the Fern CLI
65+
66+
Install the Fern CLI globally by running:
67+
68+
```bash
69+
npm install -g fern-api
70+
```
71+
72+
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.
73+
74+
### Step 5: (Optional) Use your OpenAPI specification
75+
76+
If you'd like to use the an example OpenAPI specificaton file, run:
77+
78+
```bash
79+
fern init --openapi https://petstore3.swagger.io/api/v3/openapi.json
80+
```
81+
82+
If you'd like to use your own OpenAPI specification file, run:
83+
84+
```bash
85+
fern init --openapi URL_OR_PATH_TO_YOUR_OPENAPI_SPEC
86+
```
87+
88+
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.
89+
90+
Examples:
91+
92+
```fern init --openapi https://petstore3.swagger.io/api/v3/openapi.json```
93+
94+
```fern init --openapi ../apis/openapi.yml```
95+
96+
Confirm that you see a new folder named `openapi` and that it contains the OAS file you specified, in YAML format.
97+
98+
*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)
99+
100+
### Step 6: Check that your OpenAPI specification is valid
101+
102+
Run the following command to check that your OpenAPI specification is valid:
103+
104+
```bash
105+
fern check
106+
```
107+
108+
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:[email protected]). We're here to help!
109+
110+
### Step 7: Generate your documentation
111+
112+
Generate and publish your documentation with the following command:
113+
114+
```bash
115+
fern generate --docs
116+
```
117+
118+
You will be prompted to log in and connect your GitHub account.
119+
120+
Once the documentation is generated, you will receive a URL where your documentation is published. For example:
121+
122+
```shell
123+
┌─
124+
│ ✓ petstore-openapi.docs.buildwithfern.com
125+
└─
126+
```
127+
128+
### Step 8: Customize your documentation
129+
130+
Next, modify the markdown pages located in the `docs/pages` folder, such as the Welcome page.
131+
132+
Further tailor your documentation to match your brand by adjusting settings in the `docs.yml` file.
133+
134+
To re-publish the updates to your documentation, run `fern generate --docs` again.
135+
136+
To preview updates to your documentation before publishing changes, run `fern generate --docs --preview`.
137+
138+
Fern has a built-in component library for you to use. [Explore the components.](https://docs.buildwithfern.com/generate-docs/component-library/)
139+
140+
### Step 9: Set up a custom domain
141+
142+
If you wish to use a custom subdomain like `https://docs.YOUR_ORGANIZATION.com` or a subpath like `https://YOUR_ORGANIZATION.com/docs`, you can subscribe to the [Starter plan](https://buildwithfern.com/pricing). Once subscribed, update `docs.yml` with the custom domain configuration:
143+
144+
``` yaml
145+
- url: petstore-openapi.docs.buildwithfern.com
146+
custom-domain: docs.petstore-openapi.com
147+
```
148+
149+
### Step 10: Explore advanced features
150+
151+
For advanced documentation features and options, view the full [configuration docs](https://docs.buildwithfern.com/generate-docs/overview/configuration).
152+
153+
Good luck creating beautiful and functional documentation! 🌿

fern/docs.yml

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
instances:
2+
- url: petstore-openapi.docs.buildwithfern.com
3+
4+
navigation:
5+
- section: Get Started
6+
contents:
7+
- page: Welcome
8+
path: ./docs/pages/welcome.mdx
9+
- page: SDKs
10+
path: ./docs/pages/sdks.mdx
11+
slug: sdks
12+
- api: API Reference
13+
14+
navbar-links:
15+
- type: secondary
16+
text: Contact us
17+
url: "mailto:[email protected]"
18+
- type: primary
19+
text: Join the Discord
20+
url: https://discord.com/invite/JkkXumPzcG
21+
22+
colors:
23+
accentPrimary:
24+
dark: "#adff8c"
25+
light: "#376d20"
26+
27+
logo:
28+
dark: ./docs/assets/logo_dark_mode.png
29+
light: ./docs/assets/logo_light_mode.png
30+
height: 30
31+
32+
favicon: ./docs/assets/favicon.ico

fern/docs/assets/favicon.ico

15 KB
Binary file not shown.

fern/docs/assets/logo_dark_mode.png

48 KB
Loading

fern/docs/assets/logo_light_mode.png

62.1 KB
Loading

fern/docs/pages/sdks.mdx

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Fern Docs | SDKs
3+
description: We offer client libraries/SDKs for your favorite languages, generated by Fern from your OpenAPI specification file.
4+
---
5+
6+
We provide official open-source SDKs (client libraries) for your favorite languages, such as Node.js and Python. These clients make connecting to our API faster and help avoid errors.
7+
8+
We regularly update our SDKs using [Fern](https://buildwithfern.com/?utm_source=str-d/sdks) and adhere to [semantic versioning](https://semver.org/) (semver) principles, so we won't make breaking changes in minor or patch releases.
9+
10+
## Official SDKs
11+
12+
<br />
13+
14+
<Cards>
15+
<Card
16+
title="Node.js"
17+
icon="fa-brands fa-js"
18+
href="https://github.com/fern-api/fern-typescript"
19+
/>
20+
<Card
21+
title="Python"
22+
icon="fa-brands fa-python"
23+
href="https://github.com/fern-api/fern-python"
24+
/>
25+
<Card
26+
title="Java"
27+
icon="fa-brands fa-java"
28+
href="https://github.com/fern-api/fern-java"
29+
/>
30+
<Card
31+
title="Go"
32+
icon="fa-brands fa-golang"
33+
href="https://github.com/fern-api/fern-go"
34+
/>
35+
<Card
36+
title="Ruby"
37+
icon="fa-solid fa-gem"
38+
href="https://github.com/fern-api/fern-ruby"
39+
/>
40+
<Card
41+
title="C#"
42+
icon="fa-solid fa-hashtag"
43+
href="https://github.com/fern-api/fern-csharp"
44+
/>
45+
</Cards>
46+
47+
## Request a new SDK
48+
49+
If you'd like to request an SDK for a language that we don't currently support, please [open an issue](https://github.com/fern-api/fern/labels/new-language). We prioritize languages based on demand.

0 commit comments

Comments
 (0)