diff --git a/README.md b/README.md index db6a6e1..f2c55c6 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ # Docs Starter Learn how to create beautiful documentation in under 5 minutes using an OpenAPI specification (formerly Swagger). + ## Customer Showcase @@ -19,9 +20,9 @@ Get inspired by API documentation built with Fern: [Hume](https://dev.hume.ai) | ## Requirements -- Node 18 or higher -- A [GitHub](https://github.com) account - +- Node 18 or higher +- A [GitHub](https://github.com) account + ### Step 1: Use this template 1. Click on the **Use this template** button (found at the top right of this page). You must be logged into GitHub. @@ -39,21 +40,21 @@ Open the `fern.config.json` file, which looks like this: ```json { - "organization": "Petstore", - "version": "0.17.8" + "organization": "Plantstore", + "version": "0.17.8" } ``` -Replace `"Petstore"` with your own organization name within the quotes. Spaces are permitted. Leave the `version` number unchanged. + +Replace `"Plantstore"` with your own organization name within the quotes. Spaces are permitted. Leave the `version` number unchanged. Open the `docs.yml` file and locate the `url`, which looks like this: ```yml instances: - - url: petstore-openapi.docs.buildwithfern.com + - url: plantstore.docs.buildwithfern.com ``` -Replace `petstore-openapi` 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. - +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. ### Step 4: Install the Fern CLI @@ -79,7 +80,7 @@ Once the documentation is generated, you will receive the URL where your documen ```shell ┌─ -│ ✓ petstore-openapi.docs.buildwithfern.com +│ ✓ plantstore.docs.buildwithfern.com └─ # OR @@ -100,25 +101,29 @@ You must run `fern generate --docs` after any modifications to re-generate and p To preview updates to your documentation before publishing changes, run `fern generate --docs --preview`. To use your own OpenAPI specification file or to update the existing one: + - Update or replace the OpenAPI specification file in the `openapi/` folder. -- *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). +- _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). To modify the other docs pages: + - Update the Markdown files located in the `docs/pages/` folder, such as `welcome.mdx`. To modify site styles and navigation, or to add new pages: + - See [Writing Content](https://buildwithfern.com/learn/docs/content/write-markdown). To learn about Fern's built-in component library you can use within MDX files: + - See the [Component Library](https://buildwithfern.com/learn/docs/components/overview). - + ### Step 8: Set up a custom domain 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: -``` yaml - - url: petstore-openapi.docs.buildwithfern.com - custom-domain: docs.petstore-openapi.com +```yaml +- url: plantstore.docs.buildwithfern.com + custom-domain: plantstore.dev ``` ### Step 9: Explore advanced features @@ -131,7 +136,7 @@ Good luck creating beautiful and functional documentation! 🌿 ## Support -Need help? [Set up a call](https://buildwithfern.com/contact) with an expert or email us at [support@buildwithfern.com](mailto:support@buildwithfern.com). +Need help? [Set up a call](https://buildwithfern.com/contact) with an expert or email us at [support@buildwithfern.com](mailto:support@buildwithfern.com). ## About OpenAPI (formerly Swagger) diff --git a/fern/docs.yml b/fern/docs.yml index f5939a1..6d75f18 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -1,34 +1,46 @@ instances: - - url: petstore-openapi.docs.buildwithfern.com + - url: plantstore.docs.buildwithfern.com + custom-domain: plantstore.dev + edit-this-page: + github: + owner: fern-api + repo: docs-starter + branch: main + +title: Plant Store + +layout: + searchbar-placement: header + page-width: full navigation: - section: Get Started - contents: + contents: - page: Welcome - path: ./docs/pages/welcome.mdx + path: docs/pages/welcome.mdx - page: Concepts - path: ./docs/pages/concepts.mdx + path: docs/pages/concepts.mdx - page: SDKs - path: ./docs/pages/sdks.mdx + path: docs/pages/sdks.mdx slug: sdks - api: API Reference -navbar-links: +navbar-links: - type: secondary - text: Get support - url: "mailto:support@buildwithfern.com" + text: Fork this repo + url: https://github.com/fern-api/docs-starter - type: primary text: Get a demo url: https://buildwithfern.com/contact colors: accentPrimary: - dark: "#f0c193" - light: "#af5f1b" + dark: "#4CAF50" + light: "#4CAF50" logo: - dark: ./docs/assets/logo-dark-mode.png - light: ./docs/assets/logo-light-mode.png - height: 40 + dark: docs/assets/logo-dark.svg + light: docs/assets/logo-light.svg + height: 20 -favicon: ./docs/assets/favicon.png +favicon: docs/assets/favicon.svg diff --git a/fern/docs/assets/favicon.png b/fern/docs/assets/favicon.png deleted file mode 100644 index e0be9fd..0000000 Binary files a/fern/docs/assets/favicon.png and /dev/null differ diff --git a/fern/docs/assets/favicon.svg b/fern/docs/assets/favicon.svg new file mode 100644 index 0000000..b0bedea --- /dev/null +++ b/fern/docs/assets/favicon.svg @@ -0,0 +1,9 @@ + + + + + \ No newline at end of file diff --git a/fern/docs/assets/logo-dark-mode.png b/fern/docs/assets/logo-dark-mode.png deleted file mode 100644 index 0292a1c..0000000 Binary files a/fern/docs/assets/logo-dark-mode.png and /dev/null differ diff --git a/fern/docs/assets/logo-dark.svg b/fern/docs/assets/logo-dark.svg new file mode 100644 index 0000000..9228ef7 --- /dev/null +++ b/fern/docs/assets/logo-dark.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/fern/docs/assets/logo-light-mode.png b/fern/docs/assets/logo-light-mode.png deleted file mode 100644 index a3902bf..0000000 Binary files a/fern/docs/assets/logo-light-mode.png and /dev/null differ diff --git a/fern/docs/assets/logo-light.svg b/fern/docs/assets/logo-light.svg new file mode 100644 index 0000000..7cf2ee2 --- /dev/null +++ b/fern/docs/assets/logo-light.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/fern/docs/pages/concepts.mdx b/fern/docs/pages/concepts.mdx index 223c1d7..9bd5e1b 100644 --- a/fern/docs/pages/concepts.mdx +++ b/fern/docs/pages/concepts.mdx @@ -1,19 +1,18 @@ --- title: Key Concepts -subtitle: Resources that will help you get started using the Pet Store API +subtitle: Resources that will help you get started using the Plant Store API slug: concepts -description: Learn about the Pet, Store, and User resources that comprise the Pet Store API. +description: Learn about the Plant, Store, and User resources that comprise the Plant Store API. --- -### Pet +### Plant -A pet is an animal that can be bought from the store. It has a name, a category, a status, and a list of photo URLs. +A plant can be bought from the store. It has a name, a category, a status, and a list of photo URLs. -### Store +### Store -A store has a collection of pets. It is responsible for managing the inventory of pets. Users place orders for pets from the store. +A store has a collection of plants. It is responsible for managing the inventory of plants. Users place orders for plants from the store. -### User - -A user is a person who buys pets from the store. Also known as pet parents. +### User +A user is a person who buys plants from the store. Also known as plant parents. diff --git a/fern/docs/pages/sdks.mdx b/fern/docs/pages/sdks.mdx index f53959d..c9b6f19 100644 --- a/fern/docs/pages/sdks.mdx +++ b/fern/docs/pages/sdks.mdx @@ -1,6 +1,6 @@ --- title: SDKs -subtitle: We offer client libraries/SDKs for your favorite languages, generated by Fern from your OpenAPI specification file. +subtitle: We offer client libraries/SDKs for your favorite languages, generated by Fern from your OpenAPI specification file. slug: sdks --- @@ -8,49 +8,44 @@ We provide official open-source SDKs (client libraries) for your favorite langua We regularly update our SDKs using [Fern](https://buildwithfern.com/?utm_source=docs-starter-openapi/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 +## Official SDKs - - ```bash - npm install petstore-sdk - # or - yarn add petstore-sdk - ``` - - - ```bash - pip install petstore - ``` - - - ```bash - go get -u github.com/fern-demo/petstore-go - ``` - - - ```bash - - com.buildwithfern.petstore - petstore - 0.0.1 - - # or - implementation("com.buildwithfern.petstore.java:sdk:0.0.1") - ``` - - - ```bash - gem install petstore - ``` - - - ```bash - nuget install petstore.net - ``` - + +```shell Node +bash npm install plantstore-sdk # or yarn add plantstore-sdk +``` + +```shell Python +bash pip install plantstore +``` + +```shell Go +bash go get -u github.com/fern-demo/plantstore-go +``` + +```xml Java (Maven) + + com.buildwithfern.plantstore + plantstore + 0.0.1 + +``` + +```gradle Java (Gradle) +implementation 'com.buildwithfern.plantstore:plantstore:0.0.1' +``` + +```shell Ruby +bash gem install plantstore +``` + +```shell C# +bash nuget install plantstore.net +``` + -## Request a new SDK +## Request a new SDK -If you'd like to request an SDK for a language that we don't currently support, [let us know](/welcome.mdx#get-support). We're always looking to expand our SDK offerings and would love to hear from you. \ No newline at end of file +If you'd like to request an SDK for a language that we don't currently support, [let us know](/welcome.mdx#get-support). We're always looking to expand our SDK offerings and would love to hear from you. diff --git a/fern/docs/pages/welcome.mdx b/fern/docs/pages/welcome.mdx index f4e8292..e5420a4 100644 --- a/fern/docs/pages/welcome.mdx +++ b/fern/docs/pages/welcome.mdx @@ -1,22 +1,18 @@ --- title: Welcome to our developer documentation -subtitle: Get started with the Pet Store API +subtitle: Get started with the Plant Store API slug: welcome description: Here you'll find information to get started, as well as a sample API Reference generated by Fern from an OpenAPI specification file. --- -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. +Welcome to the Plant 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. ## Getting Started -Here you'll find information about managing your pets, customers, and orders for your pet shop. +Here you'll find information about managing your plants, customers, and orders for your plant shop. - + - Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing. - operationId: findPetsByTags + operationId: findPlantsByTags parameters: - name: tags in: query @@ -169,128 +169,128 @@ paths: items: type: string responses: - '200': + "200": description: successful operation content: application/xml: schema: type: array items: - $ref: '#/components/schemas/Pet' + $ref: "#/components/schemas/Plant" application/json: schema: type: array items: - $ref: '#/components/schemas/Pet' - '400': + $ref: "#/components/schemas/Plant" + "400": description: Invalid tag value security: - - petstore_auth: - - 'write:pets' - - 'read:pets' - '/pet/{petId}': + - plantstore_auth: + - "write:plants" + - "read:plants" + "/plant/{plantId}": get: tags: - - pet - summary: Find pet by ID - description: Returns a single pet - operationId: getPetById + - plant + summary: Find plant by ID + description: Returns a single plant + operationId: getPlantById parameters: - - name: petId + - name: plantId in: path - description: ID of pet to return + description: ID of plant to return required: true schema: type: integer format: int64 responses: - '200': + "200": description: successful operation content: application/xml: schema: - $ref: '#/components/schemas/Pet' + $ref: "#/components/schemas/Plant" application/json: schema: - $ref: '#/components/schemas/Pet' - '400': + $ref: "#/components/schemas/Plant" + "400": description: Invalid ID supplied - '404': - description: Pet not found + "404": + description: Plant not found security: - api_key: [] - - petstore_auth: - - 'write:pets' - - 'read:pets' + - plantstore_auth: + - "write:plants" + - "read:plants" post: tags: - - pet - summary: Updates a pet in the store with form data - description: '' - operationId: updatePetWithForm + - plant + summary: Updates a plant in the store with form data + description: "" + operationId: updatePlantWithForm parameters: - - name: petId + - name: plantId in: path - description: ID of pet that needs to be updated + description: ID of plant that needs to be updated required: true schema: type: integer format: int64 - name: name in: query - description: Name of pet that needs to be updated + description: Name of plant that needs to be updated schema: type: string - name: status in: query - description: Status of pet that needs to be updated + description: Status of plant that needs to be updated schema: type: string responses: - '405': + "405": description: Invalid input security: - - petstore_auth: - - 'write:pets' - - 'read:pets' + - plantstore_auth: + - "write:plants" + - "read:plants" delete: tags: - - pet - summary: Delete a pet - description: '' - operationId: deletePet + - plant + summary: Delete a plant + description: "" + operationId: deletePlant parameters: - name: api_key in: header - description: '' + description: "" required: false schema: type: string - - name: petId + - name: plantId in: path - description: Pet id to delete + description: Plant id to delete required: true schema: type: integer format: int64 responses: - '400': - description: Invalid pet value + "400": + description: Invalid plant value security: - - petstore_auth: - - 'write:pets' - - 'read:pets' - '/pet/{petId}/uploadImage': + - plantstore_auth: + - "write:plants" + - "read:plants" + "/plant/{plantId}/uploadImage": post: tags: - - pet + - plant summary: Upload an image - description: '' + description: "" operationId: uploadFile parameters: - - name: petId + - name: plantId in: path - description: ID of pet to update + description: ID of plant to update required: true schema: type: integer @@ -302,31 +302,31 @@ paths: schema: type: string responses: - '200': + "200": description: successful operation content: application/json: schema: - $ref: '#/components/schemas/ApiResponse' + $ref: "#/components/schemas/ApiResponse" security: - - petstore_auth: - - 'write:pets' - - 'read:pets' + - plantstore_auth: + - "write:plants" + - "read:plants" requestBody: content: application/plain: schema: - type: string + type: string /store/inventory: get: tags: - store - summary: Returns pet inventories by status + summary: Returns plant inventories by status description: Returns a map of status codes to quantities operationId: getInventory x-swagger-router-controller: OrderController responses: - '200': + "200": description: successful operation content: application/json: @@ -341,31 +341,31 @@ paths: post: tags: - store - summary: Place an order for a pet + summary: Place an order for a plant description: Place a new order in the store operationId: placeOrder x-swagger-router-controller: OrderController responses: - '200': + "200": description: successful operation content: application/json: schema: - $ref: '#/components/schemas/Order' - '405': + $ref: "#/components/schemas/Order" + "405": description: Invalid input requestBody: content: application/json: schema: - $ref: '#/components/schemas/Order' + $ref: "#/components/schemas/Order" application/xml: schema: - $ref: '#/components/schemas/Order' + $ref: "#/components/schemas/Order" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/Order' - '/store/order/{orderId}': + $ref: "#/components/schemas/Order" + "/store/order/{orderId}": get: tags: - store @@ -384,18 +384,18 @@ paths: type: integer format: int64 responses: - '200': + "200": description: successful operation content: application/xml: schema: - $ref: '#/components/schemas/Order' + $ref: "#/components/schemas/Order" application/json: schema: - $ref: '#/components/schemas/Order' - '400': + $ref: "#/components/schemas/Order" + "400": description: Invalid ID supplied - '404': + "404": description: Order not found delete: tags: @@ -415,9 +415,9 @@ paths: type: integer format: int64 responses: - '400': + "400": description: Invalid ID supplied - '404': + "404": description: Order not found /user: post: @@ -432,40 +432,40 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" application/xml: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" requestBody: content: application/json: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" application/xml: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" description: Created user object /user/createWithList: post: tags: - user summary: Creates list of users with given input array - description: 'Creates list of users with given input array' + description: "Creates list of users with given input array" x-swagger-router-controller: UserController operationId: createUsersWithListInput responses: - '200': + "200": description: Successful operation content: application/xml: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" application/json: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" default: description: successful operation requestBody: @@ -474,13 +474,13 @@ paths: schema: type: array items: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" /user/login: get: tags: - user summary: Logs user into the system - description: '' + description: "" operationId: loginUser parameters: - name: username @@ -496,7 +496,7 @@ paths: schema: type: string responses: - '200': + "200": description: successful operation headers: X-Rate-Limit: @@ -516,46 +516,46 @@ paths: application/json: schema: type: string - '400': + "400": description: Invalid username/password supplied /user/logout: get: tags: - user summary: Logs out current logged in user session - description: '' + description: "" operationId: logoutUser parameters: [] responses: default: description: successful operation - '/user/{username}': + "/user/{username}": get: tags: - user summary: Get user by user name - description: '' + description: "" operationId: getUserByName parameters: - name: username in: path - description: 'The name that needs to be fetched. Use user1 for testing. ' + description: "The name that needs to be fetched. Use user1 for testing. " required: true schema: type: string responses: - '200': + "200": description: successful operation content: application/xml: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" application/json: schema: - $ref: '#/components/schemas/User' - '400': + $ref: "#/components/schemas/User" + "400": description: Invalid username supplied - '404': + "404": description: User not found put: tags: @@ -579,13 +579,13 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" application/xml: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" delete: tags: - user @@ -600,23 +600,23 @@ paths: schema: type: string responses: - '400': + "400": description: Invalid username supplied - '404': + "404": description: User not found externalDocs: description: Find out more about Swagger - url: 'http://swagger.io' + url: "http://swagger.io" components: schemas: Order: - x-swagger-router-model: io.swagger.petstore.model.Order + x-swagger-router-model: io.swagger.plantstore.model.Order properties: id: type: integer format: int64 example: 10 - petId: + plantId: type: integer format: int64 example: 198772 @@ -652,7 +652,7 @@ components: address: type: array items: - $ref: '#/components/schemas/Address' + $ref: "#/components/schemas/Address" xml: wrapped: true name: addresses @@ -677,7 +677,7 @@ components: name: address type: object Category: - x-swagger-router-model: io.swagger.petstore.model.Category + x-swagger-router-model: io.swagger.plantstore.model.Category properties: id: type: integer @@ -685,12 +685,12 @@ components: example: 1 name: type: string - example: Dogs + example: Ferns xml: name: category type: object User: - x-swagger-router-model: io.swagger.petstore.model.User + x-swagger-router-model: io.swagger.plantstore.model.User properties: id: type: integer @@ -723,7 +723,7 @@ components: name: user type: object Tag: - x-swagger-router-model: io.swagger.petstore.model.Tag + x-swagger-router-model: io.swagger.plantstore.model.Tag properties: id: type: integer @@ -733,8 +733,8 @@ components: xml: name: tag type: object - Pet: - x-swagger-router-model: io.swagger.petstore.model.Pet + Plant: + x-swagger-router-model: io.swagger.plantstore.model.Plant required: - name - photoUrls @@ -745,9 +745,9 @@ components: example: 10 name: type: string - example: doggie + example: fern category: - $ref: '#/components/schemas/Category' + $ref: "#/components/schemas/Category" photoUrls: type: array xml: @@ -761,18 +761,18 @@ components: xml: wrapped: true items: - $ref: '#/components/schemas/Tag' + $ref: "#/components/schemas/Tag" xml: name: tag status: type: string - description: pet status in the store + description: plant status in the store enum: - available - pending - sold xml: - name: pet + name: plant type: object ApiResponse: properties: @@ -784,35 +784,35 @@ components: message: type: string xml: - name: '##default' + name: "##default" type: object requestBodies: - Pet: + Plant: content: application/json: schema: - $ref: '#/components/schemas/Pet' + $ref: "#/components/schemas/Plant" application/xml: schema: - $ref: '#/components/schemas/Pet' - description: Pet object that needs to be added to the store + $ref: "#/components/schemas/Plant" + description: Plant object that needs to be added to the store UserArray: content: application/json: schema: type: array items: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" description: List of user object securitySchemes: - petstore_auth: + plantstore_auth: type: oauth2 flows: implicit: - authorizationUrl: 'https://petstore.swagger.io/oauth/authorize' + authorizationUrl: "https://plantstore.swagger.io/oauth/authorize" scopes: - 'write:pets': modify pets in your account - 'read:pets': read your pets + "write:plants": modify plants in your account + "read:plants": read your plants api_key: type: apiKey name: api_key