|
| 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 | +[](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! 🌿 |
0 commit comments