├── .github └── workflows │ ├── check.yml │ ├── preview-docs.yml │ └── publish-docs.yml ├── README.md └── fern ├── docs.yml ├── docs ├── assets │ ├── favicon.svg │ ├── fern-logo.png │ ├── logo-dark.svg │ └── logo-light.svg └── pages │ ├── concepts.mdx │ ├── sdks.mdx │ └── welcome.mdx ├── fern.config.json ├── generators.yml └── openapi.yaml /.github/workflows/check.yml: -------------------------------------------------------------------------------- 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 CLI tool 17 | run: npm install -g fern-api 18 | 19 | - name: Check API is valid 20 | run: fern check 21 | -------------------------------------------------------------------------------- /.github/workflows/preview-docs.yml: -------------------------------------------------------------------------------- 1 | name: preview-docs 2 | 3 | on: pull_request 4 | 5 | jobs: 6 | run: 7 | runs-on: ubuntu-latest 8 | permissions: 9 | contents: read 10 | pull-requests: write 11 | steps: 12 | - name: Checkout repository 13 | uses: actions/checkout@v4 14 | 15 | - name: Install Fern CLI tool 16 | run: npm install -g fern-api 17 | 18 | - name: Generate preview URL 19 | id: generate-docs 20 | env: 21 | FERN_TOKEN: ${{ secrets.FERN_TOKEN }} 22 | run: | 23 | OUTPUT=$(fern generate --docs --preview 2>&1) || true 24 | echo "$OUTPUT" 25 | URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()') 26 | echo "Preview URL: $URL" 27 | echo "🌿 Preview your docs: $URL" > preview_url.txt 28 | 29 | - name: Comment URL in PR 30 | uses: thollander/actions-comment-pull-request@v2.4.3 31 | with: 32 | filePath: preview_url.txt 33 | -------------------------------------------------------------------------------- /.github/workflows/publish-docs.yml: -------------------------------------------------------------------------------- 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') && github.run_number > 1 }} 12 | steps: 13 | - name: Checkout repository 14 | uses: actions/checkout@v4 15 | 16 | - name: Install Fern CLI tool 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 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 |

3 | 4 |

5 | 6 | 7 |
8 | 9 | # Docs Starter 10 | 11 | Create beautiful documentation in under 5 minutes using an OpenAPI specification (formerly Swagger). 12 | 13 |

14 | 15 | ## Customer Showcase 16 | 17 | Get inspired by API documentation built with Fern: [Hume](https://dev.hume.ai) | [Webflow](https://developers.webflow.com) | [Cartesia](https://docs.cartesia.ai) | [Cohere](https://docs.cohere.com) | [ElevenLabs](https://elevenlabs.io/docs) 18 | 19 | --- 20 | 21 | ## Requirements 22 | 23 | - Node 18 or higher 24 | - A [GitHub](https://github.com) account 25 | 26 | ### Step 1: Use this template 27 | 28 | 1. Click on the **Use this template** button (found at the top right of this page). You must be logged into GitHub. 29 | 2. Choose the option to **create a new repository**. Name it `fern-docs`. 30 | 31 | ### Step 2: Clone and open the repo in your preferred code editor 32 | 33 | Clone your newly created repository and open it in your favorite code editor (e.g., VS Code). 34 | 35 | The files and folders discussed in the following steps will be inside the `fern/` folder in your repository. 36 | 37 | ### Step 3: Customize your organization name 38 | 39 | Open the `fern.config.json` file, which looks like this: 40 | 41 | ```json 42 | { 43 | "organization": "Plantstore", 44 | "version": "0.17.8" 45 | } 46 | ``` 47 | 48 | Replace `"Plantstore"` with your own organization name within the quotes. Spaces are permitted. Leave the `version` number unchanged. 49 | 50 | Open the `docs.yml` file and locate the `url`, which looks like this: 51 | 52 | ```yml 53 | instances: 54 | - url: plantstore.docs.buildwithfern.com 55 | ``` 56 | 57 | Replace `plantstore` with your own organization's name. Use only alphanumeric characters, hyphens, and underscores. Do not use spaces, and leave the rest of the URL (`docs.buildwithfern.com`) unchanged. 58 | 59 | ### Step 4: Install the Fern CLI 60 | 61 | Install the Fern CLI globally by running: 62 | 63 | ```bash 64 | npm install -g fern-api 65 | ``` 66 | 67 | The CLI commands in the following steps must be run from within the root folder of your repository. 68 | 69 | ### Step 5: Generate your documentation 70 | 71 | Run the following command: 72 | 73 | ```bash 74 | fern generate --docs 75 | ``` 76 | 77 | You will be prompted to log in and connect your GitHub account. 78 | 79 | Once the documentation is generated, you will receive the URL where your documentation is published. For example: 80 | 81 | ```shell 82 | ┌─ 83 | │ ✓ plantstore.docs.buildwithfern.com 84 | └─ 85 | 86 | # OR 87 | 88 | ┌─ 89 | │ ✓ MY_ORGANIZATION_NAME.docs.buildwithfern.com 90 | └─ 91 | ``` 92 | 93 | ### Step 6: Try local development 94 | 95 | Preview your documentation locally. Run `fern docs dev` to access your docs on your local server at port 3000, hot-reloading as you edit your markdown and OpenAPI files. [Learn more](https://buildwithfern.com/learn/docs/getting-started/development?utm_source=github&utm_medium=readme&utm_campaign=docs-starter-openapi&utm_content=step6) or [watch a 10-second demo](https://www.loom.com/share/0a4658bd78cb45d5a9519277852c7a24?sid=3ce69ad0-bfdb-4fa1-9abf-2f4366d084b9). 96 | 97 | ### Step 7: Customize your documentation 98 | 99 | You must run `fern generate --docs` after any modifications to re-generate and publish your documentation site. 100 | 101 | To preview updates to your documentation before publishing changes, run `fern generate --docs --preview`. 102 | 103 | To use your own OpenAPI specification file or to update the existing one: 104 | 105 | - Update or replace the OpenAPI specification file in the `openapi/` folder. 106 | - _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?utm_source=github&utm_medium=readme&utm_campaign=docs-starter-openapi&utm_content=step7). 107 | 108 | To modify the other docs pages: 109 | 110 | - Update the Markdown files located in the `docs/pages/` folder, such as `welcome.mdx`. 111 | 112 | To modify site styles and navigation, or to add new pages: 113 | 114 | - See [Writing Content](https://buildwithfern.com/learn/docs/content/write-markdown?utm_source=github&utm_medium=readme&utm_campaign=docs-starter-openapi&utm_content=step7). 115 | 116 | To learn about Fern's built-in component library you can use within MDX files: 117 | 118 | - See the [Component Library](https://buildwithfern.com/learn/docs/content/components/overview?utm_source=github&utm_medium=readme&utm_campaign=docs-starter-openapi&utm_content=step7). 119 | 120 | ### Step 8: Set up a custom domain 121 | 122 | 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?utm_source=github&utm_medium=readme&utm_campaign=docs-starter-openapi&utm_content=step8). Once subscribed, update `docs.yml` with the custom domain configuration: 123 | 124 | ```yaml 125 | - url: plantstore.docs.buildwithfern.com 126 | custom-domain: plantstore.dev 127 | ``` 128 | 129 | ### Step 9: Explore advanced features 130 | 131 | For advanced documentation features and options, view the full [project structure](https://buildwithfern.com/learn/docs/getting-started/project-structure?utm_source=github&utm_medium=readme&utm_campaign=docs-starter-openapi&utm_content=step9). 132 | 133 | Good luck creating beautiful and functional documentation! 🌿 134 | 135 | --- 136 | 137 | ## Support 138 | 139 | Need help? [Set up a call](https://buildwithfern.com/contact?utm_source=github&utm_medium=readme&utm_campaign=docs-starter-openapi&utm_content=support) with an expert or email us at [support@buildwithfern.com](mailto:support@buildwithfern.com). 140 | -------------------------------------------------------------------------------- /fern/docs.yml: -------------------------------------------------------------------------------- 1 | instances: 2 | - url: plantstore.docs.buildwithfern.com # update this to {yourorg}.docs.buildwithfern.com 3 | # custom-domain: plantstore.dev # specify your custom domain when you are ready to go live 4 | 5 | title: Plant Store 6 | 7 | layout: 8 | searchbar-placement: header 9 | page-width: full 10 | 11 | navigation: 12 | - section: Get Started 13 | contents: 14 | - page: Welcome 15 | path: docs/pages/welcome.mdx 16 | - page: Concepts 17 | path: docs/pages/concepts.mdx 18 | - page: SDKs 19 | path: docs/pages/sdks.mdx 20 | slug: sdks 21 | - api: API Reference 22 | 23 | navbar-links: 24 | - type: minimal 25 | text: Fork this repo 26 | url: https://github.com/fern-api/docs-starter 27 | - type: filled 28 | text: Get a demo 29 | url: https://buildwithfern.com/contact?utm_campaign=demo&utm_medium=plantstore&utm_source=navbar 30 | - type: github 31 | value: https://github.com/fern-api/fern 32 | 33 | colors: 34 | accentPrimary: 35 | dark: "#81C784" 36 | light: "#1B5E20" 37 | 38 | logo: 39 | dark: docs/assets/logo-dark.svg 40 | light: docs/assets/logo-light.svg 41 | height: 20 42 | href: https://buildwithfern.com/?utm_campaign=demo&utm_medium=plantstore&utm_source=logo 43 | 44 | favicon: docs/assets/favicon.svg 45 | -------------------------------------------------------------------------------- /fern/docs/assets/favicon.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /fern/docs/assets/fern-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/fern-api/docs-starter/11ef54e2c9c36e20fba9159e9cde0fcbd557718c/fern/docs/assets/fern-logo.png -------------------------------------------------------------------------------- /fern/docs/assets/logo-dark.svg: -------------------------------------------------------------------------------- 1 | 15 | -------------------------------------------------------------------------------- /fern/docs/assets/logo-light.svg: -------------------------------------------------------------------------------- 1 | 15 | -------------------------------------------------------------------------------- /fern/docs/pages/concepts.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Key Concepts 3 | subtitle: Resources that will help you get started using the Plant Store API 4 | slug: concepts 5 | description: Learn about the Plant, Store, and User resources that comprise the Plant Store API. 6 | --- 7 | 8 | ### Plant 9 | 10 | A plant can be bought from the store. It has a name, a category, a status, and a list of photo URLs. 11 | 12 | ### Store 13 | 14 | A store has a collection of plants. It is responsible for managing the inventory of plants. Users place orders for plants from the store. 15 | 16 | ### User 17 | 18 | A user is a person who buys plants from the store. Also known as plant parents. 19 | -------------------------------------------------------------------------------- /fern/docs/pages/sdks.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: SDKs 3 | subtitle: We offer client libraries for your favorite languages, generated by Fern from your OpenAPI specification file. 4 | slug: sdks 5 | --- 6 | 7 | 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. 8 | 9 | We regularly update our SDKs using [Fern](https://buildwithfern.com/?utm_campaign=demo&utm_medium=plantstore&utm_source=markdown_sdks) and adhere to [semantic versioning](https://semver.org/) (semver) principles, so we won't make breaking changes in minor or patch releases. 10 | 11 | ## Official SDKs 12 | 13 | 14 | 15 | ```shell Node 16 | bash npm install plantstore-sdk # or yarn add plantstore-sdk 17 | ``` 18 | 19 | ```shell Python 20 | bash pip install plantstore 21 | ``` 22 | 23 | ```shell Go 24 | bash go get -u github.com/fern-demo/plantstore-go 25 | ``` 26 | 27 | ```xml Java (Maven) 28 | 29 | com.buildwithfern.plantstore 30 | plantstore 31 | 0.0.1 32 | 33 | ``` 34 | 35 | ```gradle Java (Gradle) 36 | implementation 'com.buildwithfern.plantstore:plantstore:0.0.1' 37 | ``` 38 | 39 | ```shell Ruby 40 | bash gem install plantstore 41 | ``` 42 | 43 | ```shell C# 44 | bash nuget install plantstore.net 45 | ``` 46 | 47 | 48 | 49 | ## Request a new SDK 50 | 51 | If you'd like to request an SDK for a language that we don't currently support, [let us know](/welcome#get-support). We're always looking to expand our SDK offerings and would love to hear from you. 52 | -------------------------------------------------------------------------------- /fern/docs/pages/welcome.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Welcome to our developer documentation 3 | subtitle: Get started with the Plant Store API 4 | slug: welcome 5 | description: Here you'll find information to get started, as well as a sample API Reference generated by Fern from an OpenAPI specification file. 6 | --- 7 | 8 | Welcome to the Plant Store API docs! This site demonstrates how to use Fern to generate API documentation from an OpenAPI file. You can [use this site template](https://github.com/fern-api/docs-starter-openapi) as a starting point for your own API documentation. 9 | 10 | ## Getting Started 11 | 12 | Here you'll find information about managing your plants, customers, and orders for your plant shop. 13 | 14 | 15 | 16 | 21 | 26 | 31 | 32 | 33 | ## Get support 34 | 35 | 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+plantstore@buildwithfern.com). We're here to help! 36 | -------------------------------------------------------------------------------- /fern/fern.config.json: -------------------------------------------------------------------------------- 1 | { 2 | "organization": "plantstore", 3 | "version": "0.57.29" 4 | } -------------------------------------------------------------------------------- /fern/generators.yml: -------------------------------------------------------------------------------- 1 | # yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json 2 | 3 | api: 4 | specs: 5 | - openapi: openapi.yaml 6 | -------------------------------------------------------------------------------- /fern/openapi.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.1.0 2 | servers: 3 | - url: https://api.plantstore.dev/v3 4 | description: Demo server 5 | info: 6 | description: | 7 | This is a sample Plant Store Server based on the OpenAPI 3.1 specification. It provides a comprehensive set of endpoints for managing plants, orders, and user authentication. 8 | 9 | ### Key Features 10 | - **Rich API Documentation**: Includes detailed examples and schema definitions. 11 | - **Search Functionality**: Search for plants by tags or status. 12 | - **User-Friendly Endpoints**: Login, logout, and retrieve user information. 13 | - **Error Handling**: Clear and consistent error responses. 14 | 15 | ### Developer Notes 16 | - Use `api_key` for store endpoints requiring authorization. 17 | - OAuth2 flow is available for plant-specific operations. 18 | 19 | version: 1.0.18 20 | title: Swagger Plant Store - OpenAPI 3.1 21 | termsOfService: "http://buildwithfern.com/tos/" 22 | contact: 23 | name: Plant Store API Support 24 | url: https://support.plantstore.dev 25 | email: support@buildwithfern.com 26 | license: 27 | name: Apache 2.0 28 | url: "http://www.apache.org/licenses/LICENSE-2.0.html" 29 | tags: 30 | - name: plant 31 | description: Everything about your Plants 32 | externalDocs: 33 | description: Plant API Documentation 34 | url: https://docs.plantstore.dev/plants 35 | - name: store 36 | description: Access to Plantstore orders 37 | externalDocs: 38 | description: Order Management Guide 39 | url: https://docs.plantstore.dev/orders 40 | - name: user 41 | description: Operations about user 42 | externalDocs: 43 | description: User Management API 44 | url: https://docs.plantstore.dev/users 45 | paths: 46 | /plant: 47 | post: 48 | tags: 49 | - plant 50 | summary: Add a new plant to the store 51 | operationId: addPlant 52 | requestBody: 53 | description: Details of the plant to add 54 | required: true 55 | content: 56 | application/json: 57 | schema: 58 | $ref: "#/components/schemas/Plant" 59 | examples: 60 | example1: 61 | summary: Add a Fern Plant 62 | value: 63 | name: "Fern" 64 | category: "Indoor" 65 | tags: ["green", "leafy"] 66 | status: "available" 67 | responses: 68 | "200": 69 | description: Plant successfully added 70 | content: 71 | application/json: 72 | schema: 73 | $ref: "#/components/schemas/PlantResponse" 74 | examples: 75 | exampleResponse: 76 | summary: Successful Plant Addition 77 | value: 78 | id: 101 79 | name: "Fern" 80 | status: "available" 81 | tags: ["green", "leafy"] 82 | "405": 83 | description: Invalid input 84 | put: 85 | tags: 86 | - plant 87 | summary: Update an existing plant 88 | operationId: updatePlant 89 | requestBody: 90 | description: Updated details of the plant 91 | required: true 92 | content: 93 | application/json: 94 | schema: 95 | $ref: "#/components/schemas/Plant" 96 | examples: 97 | example1: 98 | summary: Update plant status 99 | value: 100 | name: "Fern" 101 | category: "Indoor" 102 | tags: ["green", "leafy"] 103 | status: "sold" 104 | responses: 105 | "200": 106 | description: Plant successfully updated 107 | content: 108 | application/json: 109 | schema: 110 | $ref: "#/components/schemas/PlantResponse" 111 | examples: 112 | exampleResponse: 113 | summary: Successful Plant Update 114 | value: 115 | id: 101 116 | name: "Fern" 117 | status: "sold" 118 | tags: ["green", "leafy"] 119 | "400": 120 | description: Invalid ID supplied 121 | "404": 122 | description: Plant not found 123 | /plant/search/status: 124 | get: 125 | tags: 126 | - plant 127 | summary: Search plants by status 128 | description: Filter plants based on their current status. 129 | operationId: searchPlantsByStatus 130 | parameters: 131 | - name: status 132 | in: query 133 | description: The status of plants to search for. 134 | required: false 135 | schema: 136 | type: string 137 | enum: [available, pending, sold] 138 | responses: 139 | "200": 140 | description: List of plants matching the status filter 141 | content: 142 | application/json: 143 | schema: 144 | type: array 145 | items: 146 | $ref: "#/components/schemas/PlantResponse" 147 | examples: 148 | exampleResponse: 149 | summary: Plants with status available 150 | value: 151 | - id: 101 152 | name: "Fern" 153 | status: "available" 154 | tags: ["green", "leafy"] 155 | - id: 102 156 | name: "Palm" 157 | status: "available" 158 | tags: ["tropical"] 159 | /plant/search/tags: 160 | get: 161 | tags: 162 | - plant 163 | summary: Search plants by tags 164 | description: Filter plants based on associated tags. 165 | operationId: searchPlantsByTags 166 | parameters: 167 | - name: tags 168 | in: query 169 | description: Tags to filter plants (comma-separated). 170 | schema: 171 | type: array 172 | items: 173 | type: string 174 | responses: 175 | "200": 176 | description: List of plants matching the tags filter 177 | content: 178 | application/json: 179 | schema: 180 | type: array 181 | items: 182 | $ref: "#/components/schemas/PlantResponse" 183 | examples: 184 | exampleResponse: 185 | summary: Plants filtered by tags 186 | value: 187 | - id: 101 188 | name: "Fern" 189 | status: "available" 190 | tags: ["green", "leafy"] 191 | - id: 103 192 | name: "Cactus" 193 | status: "available" 194 | tags: ["spiky", "desert"] 195 | /plant/{plantId}: 196 | get: 197 | tags: 198 | - plant 199 | summary: Find plant by ID 200 | description: Retrieve a plant's details by its ID. 201 | operationId: getPlantById 202 | parameters: 203 | - name: plantId 204 | in: path 205 | description: ID of the plant to retrieve 206 | required: true 207 | schema: 208 | type: integer 209 | responses: 210 | "200": 211 | description: Details of the requested plant 212 | content: 213 | application/json: 214 | schema: 215 | $ref: "#/components/schemas/PlantResponse" 216 | examples: 217 | exampleResponse: 218 | summary: Plant details 219 | value: 220 | id: 101 221 | name: "Fern" 222 | status: "available" 223 | tags: ["green", "leafy"] 224 | /user/auth/login: 225 | get: 226 | tags: 227 | - user 228 | summary: Logs user into the system 229 | operationId: loginUser 230 | parameters: 231 | - name: username 232 | in: query 233 | description: The username for login 234 | schema: 235 | type: string 236 | - name: password 237 | in: query 238 | description: The password for login 239 | schema: 240 | type: string 241 | responses: 242 | "200": 243 | description: Successful login 244 | headers: 245 | Set-Cookie: 246 | description: Session token for user authentication 247 | schema: 248 | type: string 249 | content: 250 | application/json: 251 | schema: 252 | $ref: "#/components/schemas/UserAuthResponse" 253 | examples: 254 | exampleResponse: 255 | summary: Successful login response 256 | value: 257 | token: "abc123token" 258 | expiresIn: 3600 259 | /user/auth/logout: 260 | get: 261 | tags: 262 | - user 263 | summary: Logs out current logged-in user session 264 | operationId: logoutUser 265 | responses: 266 | default: 267 | description: Successful logout 268 | /user/{username}: 269 | get: 270 | tags: 271 | - user 272 | summary: Get user by username 273 | description: Retrieve user details using their username. 274 | operationId: getUserByName 275 | parameters: 276 | - name: username 277 | in: path 278 | description: Username of the user to retrieve 279 | required: true 280 | schema: 281 | type: string 282 | responses: 283 | "200": 284 | description: User details retrieved successfully 285 | content: 286 | application/json: 287 | schema: 288 | $ref: "#/components/schemas/User" 289 | examples: 290 | exampleResponse: 291 | summary: User details response 292 | value: 293 | id: 1 294 | username: "john_doe" 295 | email: "john@example.com" 296 | components: 297 | schemas: 298 | Plant: 299 | type: object 300 | properties: 301 | name: 302 | type: string 303 | category: 304 | type: string 305 | tags: 306 | type: array 307 | items: 308 | type: string 309 | status: 310 | type: string 311 | enum: [available, pending, sold] 312 | PlantResponse: 313 | type: object 314 | properties: 315 | id: 316 | type: integer 317 | name: 318 | type: string 319 | status: 320 | type: string 321 | tags: 322 | type: array 323 | items: 324 | type: string 325 | UserAuthResponse: 326 | type: object 327 | properties: 328 | token: 329 | type: string 330 | description: Authentication token 331 | expiresIn: 332 | type: integer 333 | description: Token expiration time in seconds 334 | User: 335 | type: object 336 | properties: 337 | id: 338 | type: integer 339 | username: 340 | type: string 341 | email: 342 | type: string 343 | --------------------------------------------------------------------------------