diff --git a/README.md b/README.md index 5de3ee0..757f14e 100644 --- a/README.md +++ b/README.md @@ -48,13 +48,13 @@ instances: 1. Install the Fern CLI by running: ```bash -npm install -g fern-api +$ npm install -g fern-api ``` 2. Generate your documentation with the following command: ```bash -fern generate --docs +$ fern generate --docs ``` You will be prompted to log in and connect your GitHub account. @@ -67,12 +67,19 @@ Once the documentation is generated, you will receive a URL where your documenta └─ ``` -### Step 5: Customize Your Documentation +### Step 5: Choose an API definition format -To get started, replace the provided OpenAPI specification with your own. Then, modify the markdown pages located in the [content](fern/docs/content/) directory. You can further tailor your documentation to match your brand by adjusting settings in the [docs.yml](fern/docs.yml) file. +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: Set Up a Custom Domain +### 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: @@ -83,13 +90,14 @@ If you wish to use a custom domain like `docs.your-organization.com` or a subdir ### Step 7: Explore Advanced Features -For advanced documentation features and options, visit the [Fern Docs Advanced Repo](https://github.com/fern-api/docs-advanced). +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! 🌿 +Good luck creating beautiful and functional documentation! 🌿 \ No newline at end of file diff --git a/fern/definition/__package__.yml b/fern/definition/__package__.yml new file mode 100644 index 0000000..9de1ee7 --- /dev/null +++ b/fern/definition/__package__.yml @@ -0,0 +1,92 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json + +types: + PlantInput: + docs: Input for adding a new plant. + properties: + name: string + category: + type: optional + photoUrls: + type: map + status: + type: optional + + OwnerId: + type: string + docs: Unique identifier for an owner. + + PlantOwner: + properties: + id: + type: optional + age: + type: optional + plants: + type: optional> + + OwnerAge: + docs: Age category of an owner. + enum: + - name: child + value: child + - name: adult + value: adult + - name: senior + value: senior + + PlantOwnerId: + type: OwnerId + docs: Identifier for a plant owner. + + PlantId: + type: string + docs: Unique identifier for a plant. + + CategoryId: + type: string + docs: Unique identifier for a plant category. + + PlantCategory: + docs: Category information for a plant. + properties: + id: + type: CategoryId + name: string + + PlantStatus: + docs: Status of a plant. + enum: + - name: available + value: available + - name: pending + value: pending + - name: sold + value: sold + + Plant: + docs: Information about a plant. + properties: + id: + type: optional + category: + type: optional + name: + type: optional + photoUrls: + type: optional> + status: + type: optional + + Error: + properties: + message: string + +errors: + BadRequestError: + status-code: 400 + type: Error + + NotFoundError: + status-code: 404 + type: Error diff --git a/fern/definition/api.yml b/fern/definition/api.yml new file mode 100644 index 0000000..60250b6 --- /dev/null +++ b/fern/definition/api.yml @@ -0,0 +1,7 @@ +imports: + root: __package__.yml +name: api +display-name: Plant Store API +error-discrimination: + strategy: status-code +auth: bearer diff --git a/fern/definition/owner.yml b/fern/definition/owner.yml new file mode 100644 index 0000000..2e8e50c --- /dev/null +++ b/fern/definition/owner.yml @@ -0,0 +1,43 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json + +imports: + root: __package__.yml + +service: + auth: false + base-path: "" + endpoints: + addOwner: + path: /owners + method: POST + auth: false + display-name: Add a new owner + request: + name: PlantOwnerInput + body: + properties: + name: string + age: + type: root.OwnerAge + plants: + type: list + response: + docs: Owner added successfully + type: root.PlantOwner + errors: + - root.BadRequestError + + deleteOwner: + path: /owners/{ownerId} + method: DELETE + auth: false + path-parameters: + ownerId: + docs: Identifier for an owner. + type: root.OwnerId + display-name: Delete an owner + errors: + - root.NotFoundError + examples: + - path-parameters: + ownerId: owner-id diff --git a/fern/definition/plant.yml b/fern/definition/plant.yml new file mode 100644 index 0000000..f0f6a66 --- /dev/null +++ b/fern/definition/plant.yml @@ -0,0 +1,56 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json + +imports: + root: __package__.yml + +service: + auth: false + base-path: "" + endpoints: + addPlant: + path: /plants + method: POST + auth: false + display-name: Add a new plant + request: + body: + type: root.PlantInput + docs: Input for adding a new plant. + errors: + - root.BadRequestError + + getPlantById: + path: /plants/{plantId} + method: GET + auth: false + path-parameters: + plantId: + docs: Identifier for a plant. + type: root.PlantId + display-name: Get a plant + response: + docs: Plant retrieved successfully + type: root.Plant + errors: + - root.NotFoundError + examples: + - path-parameters: + plantId: plant-id + response: + body: + status: available + + deletePlantById: + path: /plants/{plantId} + method: DELETE + auth: false + path-parameters: + plantId: + docs: Identifier for a plant. + type: root.PlantId + display-name: Delete a plant + errors: + - root.NotFoundError + examples: + - path-parameters: + plantId: plant-id diff --git a/fern/docs.yml b/fern/docs.yml index 12a287f..64d3553 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -22,9 +22,12 @@ navbar-links: colors: accentPrimary: - dark: "#1FBAB4" - light: "#126d69" + dark: "#18ed9d" + light: "#13A06C" logo: - dark: ./docs/assets/fern_logo.png - light: ./docs/assets/fern_logo.png + dark: ./docs/assets/logo_white.png + light: ./docs/assets/logo_black.png + height: 25 + +favicon: ./docs/assets/favicon.png \ No newline at end of file diff --git a/fern/docs/assets/favicon.png b/fern/docs/assets/favicon.png new file mode 100644 index 0000000..60e609b Binary files /dev/null and b/fern/docs/assets/favicon.png differ diff --git a/fern/docs/assets/fern_logo.png b/fern/docs/assets/fern_logo.png deleted file mode 100644 index 85f2da5..0000000 Binary files a/fern/docs/assets/fern_logo.png and /dev/null differ diff --git a/fern/docs/assets/helloworld.png b/fern/docs/assets/helloworld.png deleted file mode 100644 index 590a105..0000000 Binary files a/fern/docs/assets/helloworld.png and /dev/null differ diff --git a/fern/docs/assets/logo_black.png b/fern/docs/assets/logo_black.png new file mode 100644 index 0000000..9b0fedd Binary files /dev/null and b/fern/docs/assets/logo_black.png differ diff --git a/fern/docs/assets/logo_white.png b/fern/docs/assets/logo_white.png new file mode 100644 index 0000000..889e83b Binary files /dev/null and b/fern/docs/assets/logo_white.png differ diff --git a/fern/generators.yml b/fern/generators.yml index 0967ef4..e9c3d93 100644 --- a/fern/generators.yml +++ b/fern/generators.yml @@ -1 +1,15 @@ -{} +# To run the code generator +# 1. `$ npm i -g fern-api` +# 2. `$ fern generate` + +default-group: local +groups: + local: + generators: + - name: fernapi/fern-openapi + version: 0.0.28 + config: + format: yaml + output: + location: local-file-system + path: ../openapi \ No newline at end of file diff --git a/fern/openapi/openapi.yml b/fern/openapi/openapi.yml deleted file mode 100644 index 2ee5276..0000000 --- a/fern/openapi/openapi.yml +++ /dev/null @@ -1,233 +0,0 @@ -openapi: 3.0.3 -info: - title: Plant Store API - version: 1.0.0 - description: An API for managing plant store operations. -paths: - /owners: - post: - summary: Add a new owner as a customer of the store. - operationId: addOwner - tags: - - Owner - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/PlantOwnerInput' - responses: - '201': - description: Owner added successfully - content: - application/json: - schema: - $ref: '#/components/schemas/PlantOwner' - '400': - $ref: '#/components/responses/BadRequest' - /owners/{ownerId}: - delete: - summary: Delete an owner by ID - operationId: deleteOwner - tags: - - Owner - parameters: - - $ref: '#/components/parameters/OwnerId' - responses: - '204': - description: Owner deleted successfully - '404': - $ref: '#/components/responses/NotFound' - /plants: - post: - summary: Add a new plant to the store. - operationId: addPlant - tags: - - Plant - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/PlantInput' - responses: - '201': - description: Plant added successfully - '400': - $ref: '#/components/responses/BadRequest' - /plants/{plantId}: - get: - summary: Get a plant by ID - operationId: getPlantById - tags: - - Plant - parameters: - - $ref: '#/components/parameters/PlantId' - responses: - '200': - description: Plant retrieved successfully - content: - application/json: - schema: - $ref: '#/components/schemas/Plant' - '404': - $ref: '#/components/responses/NotFound' - delete: - summary: Delete a plant by ID - operationId: deletePlantById - tags: - - Plant - parameters: - - $ref: '#/components/parameters/PlantId' - responses: - '204': - description: Plant deleted successfully - '404': - $ref: '#/components/responses/NotFound' -components: - schemas: - OwnerId: - type: string - format: uuid - description: Unique identifier for an owner. - PlantOwner: - type: object - properties: - id: - $ref: '#/components/schemas/PlantOwnerId' - age: - $ref: '#/components/schemas/OwnerAge' - plants: - type: array - items: - $ref: '#/components/schemas/Plant' - OwnerAge: - type: string - enum: - - child - - adult - - senior - description: Age category of an owner. - PlantOwnerId: - allOf: - - $ref: '#/components/schemas/OwnerId' - description: Identifier for a plant owner. - PlantOwnerInput: - type: object - properties: - name: - type: string - age: - $ref: '#/components/schemas/OwnerAge' - plants: - type: array - items: - $ref: '#/components/schemas/PlantInput' - required: - - name - - age - - plants - description: Input for adding a new owner. - PlantInput: - type: object - properties: - name: - type: string - category: - $ref: '#/components/schemas/PlantCategory' - photoUrls: - type: object - additionalProperties: - type: string - status: - $ref: '#/components/schemas/PlantStatus' - required: - - name - - photoUrls - description: Input for adding a new plant. - PlantId: - type: string - format: uuid - description: Unique identifier for a plant. - CategoryId: - type: string - format: uuid - description: Unique identifier for a plant category. - PlantCategory: - type: object - properties: - id: - $ref: '#/components/schemas/CategoryId' - name: - type: string - required: - - id - - name - description: Category information for a plant. - PlantStatus: - type: string - enum: - - available - - pending - - sold - description: Status of a plant. - Plant: - type: object - properties: - id: - $ref: '#/components/schemas/PlantId' - category: - $ref: '#/components/schemas/PlantCategory' - name: - type: string - photoUrls: - type: object - additionalProperties: - type: string - status: - $ref: '#/components/schemas/PlantStatus' - description: Information about a plant. - Error: - type: object - properties: - message: - type: string - required: - - message - responses: - BadRequest: - description: Bad request - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - NotFound: - description: Resource not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - parameters: - OwnerId: - name: ownerId - in: path - required: true - schema: - $ref: '#/components/schemas/OwnerId' - description: Identifier for an owner. - PlantId: - name: plantId - in: path - required: true - schema: - $ref: '#/components/schemas/PlantId' - description: Identifier for a plant. - securitySchemes: - BearerAuth: - type: http - scheme: bearer -servers: - - url: https://api.plantstore.com - description: Production Server - - url: https://sandbox.plantstore.com - description: Sandbox Server