diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml new file mode 100644 index 0000000..ad753be --- /dev/null +++ b/.github/workflows/preview-docs.yml @@ -0,0 +1,52 @@ +name: fern + +on: pull_request + +jobs: + check: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "18" + + - name: Install Fern + run: npm install -g fern-api + + - name: Validate API configuration + run: fern check + + preview-docs: + needs: check + runs-on: ubuntu-latest + permissions: write-all + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "18" + + - name: Install Fern + run: npm install -g fern-api + + - name: Generate preview URL + id: generate-docs + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + run: | + OUTPUT="$(fern generate --docs --preview)" + echo "Command Output: $OUTPUT" + URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()') + echo "Preview your docs: $URL" > preview_url.txt + + - name: Comment URL in PR + uses: thollander/actions-comment-pull-request@v2.4.3 + with: + filePath: preview_url.txt diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..f72653d --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,44 @@ +name: fern + +on: + push: + branches: + - main + +jobs: + check: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "18" + + - name: Install Fern + run: npm install -g fern-api + + - name: Validate API configuration + run: fern check + + publish-docs: + needs: fern-check + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "18" + + - name: Install Fern + run: npm install -g fern-api + + - name: Publish Docs + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + run: fern generate --docs --log-level debug diff --git a/README.md b/README.md new file mode 100644 index 0000000..9522e2a --- /dev/null +++ b/README.md @@ -0,0 +1,115 @@ +
+
+ + header + + +
+ +# Docs Starter + +Create beautiful documentation in under 5 minutes. Here's [an example!](https://your-organization.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 + +### Step 1: Use This Template + +1. Click on the "Use this template" button. +2. Create a new repository. Name it anything you like, `docs` is a common naming choice. + +### Step 2: Open in Your Preferred IDE + +Clone your newly created repository and open it in your favorite integrated development environment (IDE) or code editor. + +### Step 3: Customize Organization Name + +In the fern.config.json file, replace the placeholder organization name with your actual organization name. For example: + +```json +{ + "organization": "YourOrganization", + "version": "0.16.25" +} +``` + +Also, in the docs.yml file, update the docs URL to match your organization's naming convention. For example: + +```yml +instances: + - url: your-organization.docs.buildwithfern.com +``` + +### Step 4: Generate Your Documentation + +1. Install the Fern CLI by running: + +```bash +npm install -g fern-api +``` + +1. Generate your documentation with the following command: + +```bash +fern generate --docs +``` + +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: + +```shell +┌─ +│ ✓ your-organization.docs.buildwithfern.com +└─ +``` + +### Step 5: Choose an API definition format + +If you're using a [Fern Definition](https://docs.buildwithfern.com/api-definition/fern-definition/overview), you can edit the files within the [`definition`](/fern/definition/) folder. + +If you're using an [OpenAPI Specification](https://docs.buildwithfern.com/api-definition/openapi/extensions), then run the command: `fern generate`. You'll see a new folder created called `openapi` that contains your spec. You can edit this spec to make it your own OR copy and paste a spec you already have. Then, delete the `definition` folder. + +### Step 6: Customize Your Documentation + +Next, modify the markdown pages located in the [pages](fern/docs/pages/) directory. You can further tailor your documentation to match your brand by adjusting settings in the [docs.yml](fern/docs.yml) file. + +Fern has a built-in component library for you to use. [Explore the components.](https://docs.buildwithfern.com/generate-docs/component-library/) + +### Step 6: Set Up a Custom Domain + +If you wish to use a custom domain like `docs.your-organization.com` or a subdirectory like `your-organization.com/docs`, you can subscribe to the [Starter plan](https://buildwithfern.com/pricing). Once subscribed, update [docs.yml](fern/docs.yml) with the custom domain configuration: + +``` yaml + - url: your-organization.docs.buildwithfern.com + custom-domain: docs.your-organization.com +``` + +### Step 7: Explore Advanced Features + +For advanced documentation features and options, visit the [Fern Docs](https://docs.buildwithfern.com/generate-docs). + +**Advanced features** include: + +- Versioning +- Changelog +- Multiple APIs +- Custom background +- Bring your own fonts + +Good luck creating beautiful and functional documentation! 🌿 diff --git a/fern/definition/actor.yml b/fern/definition/actor.yml new file mode 100644 index 0000000..2df99a2 --- /dev/null +++ b/fern/definition/actor.yml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json + +imports: + movie: movie.yml + +service: + auth: false + base-path: /actors + endpoints: + listMovies: + display-name: List Movies for an Actor + docs: This endpoint will return a list of movies that Morgan Freeman (Actor ID `nm0000151`) has acted in. We'll list just 5 movies, because he's acted in over 153! + method: GET + path: /list-movies/{actorId} + path-parameters: + actorId: ActorId + response: list + examples: + - name: Morgan Freeman + path-parameters: + actorId: nm0000151 + response: + body: + - "The Shawshank Redemption" + - "The Power of One" + - "Unforgiven" + - "Outbreak" + - "Se7en" + +types: + ActorId: + type: string + docs: The unique identifier for an actor in the database + +errors: + ActorDoesNotExistError: + status-code: 404 + type: ActorId diff --git a/fern/definition/api.yml b/fern/definition/api.yml new file mode 100644 index 0000000..ad2a3c1 --- /dev/null +++ b/fern/definition/api.yml @@ -0,0 +1,7 @@ +name: imdb-api +error-discrimination: + strategy: status-code +auth: bearer +environments: + Sandbox: https://sandbox.example.com +default-environment: Sandbox \ No newline at end of file diff --git a/fern/definition/movie.yml b/fern/definition/movie.yml new file mode 100644 index 0000000..b81eebf --- /dev/null +++ b/fern/definition/movie.yml @@ -0,0 +1,103 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json + +service: + auth: false + base-path: /movies + endpoints: + create: + docs: Add a movie to the database + display-name: Create a Movie + method: POST + path: /create-movie + request: CreateMovieRequest + response: MovieId + examples: + - name: Shawshank Example + request: + title: The Shawshank Redemption + rating: 9.3 + response: + body: tt0111161 + + get: + docs: Retrieve a movie from the database based on the ID + display-name: Get a Movie by ID + method: GET + path: /{id} + path-parameters: + id: MovieId + response: Movie + errors: + - MovieDoesNotExistError + examples: + # Success response + - path-parameters: + id: tt9398640 + response: + body: + id: tt9398640 + title: "Between Two Ferns: The Movie" + rating: 6.1 + year: "2019" + # Error response + - path-parameters: + id: tt1234 + response: + error: MovieDoesNotExistError + body: tt1234 + + delete: + display-name: Delete a Movie by ID + method: DELETE + path: /{id} + path-parameters: + id: MovieId + examples: + - path-parameters: + id: tt2294629 + errors: + - MovieDoesNotExistError + + update: + display-name: Update a Movie by ID + method: PUT + path: /{id} + path-parameters: + id: MovieId + request: UpdateMovieRequest + examples: + - path-parameters: + id: tt2294629 + request: + year: "2019" + errors: + - MovieDoesNotExistError +types: + MovieId: + type: string + docs: The unique identifier for a movie in the database + + Movie: + properties: + id: MovieId + title: string + rating: + type: double + docs: The rating scale out of ten stars + year: string + + CreateMovieRequest: + properties: + title: string + rating: double + + UpdateMovieRequest: + properties: + title: optional + rating: optional + year: optional + +errors: + MovieDoesNotExistError: + status-code: 404 + type: MovieId diff --git a/fern/docs.yml b/fern/docs.yml new file mode 100644 index 0000000..2cf121e --- /dev/null +++ b/fern/docs.yml @@ -0,0 +1,33 @@ +instances: + - url: your-organization.docs.buildwithfern.com + +title: Your Organization | Docs + +navigation: + - section: Getting started + contents: + - page: Welcome + path: ./docs/pages/welcome.mdx + - page: SDKs + path: ./docs/pages/sdks.mdx + - api: API Reference + +navbar-links: + - type: secondary + text: Contact us + url: "mailto:support@buildwithfern.com" + - type: primary + text: Join the Discord + url: https://discord.com/invite/JkkXumPzcG + +colors: + accentPrimary: + dark: "#adff8c" + light: "#376d20" + +logo: + dark: ./docs/assets/logo_dark_mode.png + light: ./docs/assets/logo_light_mode.png + height: 30 + +favicon: ./docs/assets/favicon.ico \ No newline at end of file diff --git a/fern/docs/assets/favicon.ico b/fern/docs/assets/favicon.ico new file mode 100644 index 0000000..c3dda24 Binary files /dev/null and b/fern/docs/assets/favicon.ico differ diff --git a/fern/docs/assets/logo_dark_mode.png b/fern/docs/assets/logo_dark_mode.png new file mode 100644 index 0000000..7d8d91a Binary files /dev/null and b/fern/docs/assets/logo_dark_mode.png differ diff --git a/fern/docs/assets/logo_light_mode.png b/fern/docs/assets/logo_light_mode.png new file mode 100644 index 0000000..7d23a66 Binary files /dev/null and b/fern/docs/assets/logo_light_mode.png differ diff --git a/fern/docs/pages/sdks.mdx b/fern/docs/pages/sdks.mdx new file mode 100644 index 0000000..081a90e --- /dev/null +++ b/fern/docs/pages/sdks.mdx @@ -0,0 +1,44 @@ +We provide official open-source SDKs (client libraries) for your favorite platforms. These clients make connecting to our API faster and help avoid errors. + +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. + +## Official SDKs + +
+ + + + + + + + + + +## Request a new SDK + +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. diff --git a/fern/docs/pages/welcome.mdx b/fern/docs/pages/welcome.mdx new file mode 100644 index 0000000..707a3ca --- /dev/null +++ b/fern/docs/pages/welcome.mdx @@ -0,0 +1,96 @@ + +Start building beautiful documentation in under 5 minutes. + + +## Hello World 👋 + +Welcome to our documentation! Here you'll find information to get started as well as our API Reference. + +## Frequently Visited Resources + + + + + + +
+ + + + + + +## Getting started + +To get started, customize the links, content, and theme to match your brand! + +## SDKs + +In addition to documentation, Fern can generate SDKs (client libraries) in popular programming languages. That way, you can offer users an experience such as: + + + + ```bash + npm install your-organization + # or + yarn add your-organization + ``` + + + ```bash + pip install your-organization + ``` + + + ```bash + go get -u github.com/your-organization/go + ``` + + + ```bash + + com.your-organization + your-organization + 2.0.0 + + # or + implementation("com.your-organization.java:sdk:2.0.0") + ``` + + + ```bash + gem install your-organization + ``` + + + ```bash + nuget install your-organization.net + ``` + + + +## Need help? + +We have three channels to assist: + +1. Join the [Discord](https://discord.com/invite/JkkXumPzcG) where you can get help from Fern developers and community members. + +2. Open an issue on [GitHub](https://github.com/fern-api/docs-starter/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 48 hours. diff --git a/fern/fern.config.json b/fern/fern.config.json new file mode 100644 index 0000000..f8a4857 --- /dev/null +++ b/fern/fern.config.json @@ -0,0 +1,4 @@ +{ + "organization": "your-organization", + "version": "0.16.25" +} \ No newline at end of file diff --git a/fern/generators.yml b/fern/generators.yml new file mode 100644 index 0000000..84a4c75 --- /dev/null +++ b/fern/generators.yml @@ -0,0 +1,23 @@ +# To invoke the code generators +# 1. Install Fern: `npm i -g fern-api` +# 2. Run: `fern generate` + +default-group: local +groups: + local: + generators: + # Generates an OpenAPI spec from your Fern Definition + - name: fernapi/fern-openapi + version: 0.0.28 + config: + format: yaml + output: + location: local-file-system + path: ../generated/openapi + + # Generates a Node.js client SDK from your Fern Definition + - name: fernapi/fern-typescript-node-sdk + version: 0.9.0 + output: + location: local-file-system + path: ../generated/sdk/node \ No newline at end of file