From fdae2bf0872cb691a7443d843cc85643faa35703 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Fri, 22 Aug 2025 18:54:26 -0400 Subject: [PATCH] move postman info into sdks section, break up into quickstart/publish --- .../docs/pages/integrations/postman.mdx | 90 ++----------------- .../postman/publishing-to-postman.mdx | 46 ++++++++++ .../sdks/overview/postman/quickstart.mdx | 69 ++++++++++++++ fern/products/sdks/sdks.yml | 8 ++ 4 files changed, 131 insertions(+), 82 deletions(-) create mode 100644 fern/products/sdks/overview/postman/publishing-to-postman.mdx create mode 100644 fern/products/sdks/overview/postman/quickstart.mdx diff --git a/fern/products/docs/pages/integrations/postman.mdx b/fern/products/docs/pages/integrations/postman.mdx index 8623cc0d8..b60270097 100644 --- a/fern/products/docs/pages/integrations/postman.mdx +++ b/fern/products/docs/pages/integrations/postman.mdx @@ -1,9 +1,14 @@ --- title: "Postman Integration" description: "Generate a postman collection full of example requests and responses" -subtitle: "Generate a postman collection full of example requests and responses" --- +You can generate a Postman collection full of example requests and responses and +publish your collection to Postman. The configuration for the postman generator +lives in your fern folder, in a file called +[`generators.yml`](/sdks/overview/github#generatorsyml). + + ## Showcase @@ -15,93 +20,14 @@ subtitle: "Generate a postman collection full of example requests and responses" icon={} iconSize={12} /> - -} - iconSize={12} -/> - ## Getting started -The configuration for the postman generator lives in your fern folder, in a file -called [`generators.yml`](/learn/api-definition/introduction/what-is-the-fern-folder#generatorsyml). - -### **Step 1**: Configure your `generators.yml` - -Start by running the following command: - -```sh -fern add fern-postman --group postman -``` - -Once the command completes, you will see the following configuration added: - -```yaml title="generators.yml" {2-8} -groups: - postman: - generators: - - name: fernapi/fern-postman - version: 0.0.45 - output: - location: local-file-system - path: ../postman -``` - -### **Step 2**: Generate a `collection.json` - -Start by running the following command: - -```sh -fern generate --group postman -``` - -This will trigger postman collection on Fern's cloud. Once complete, you'll see a `collection.json`: - -```bash {4-5} -fern/ - ├─ fern.config.json - ├─ generators.yml -postman - ├─ collection.json -``` +For information on how to generate a Postman collection, see the [Postman Quickstart](/products/sdks/overview/postman/quickstart.mdx). ## Publishing -If you'd like Fern to publish the collection directly to Postman instead, you can modify your `generators.yml` configuration -in the following way: - -```yaml title="generators.yml" {6-9} -generators: - postman: - generators: - - name: fernapi/fern-postman - version: 0.4.0 - output: - location: postman - api-key: ${POSTMAN_API_KEY} - workspace-id: 07e228e5-3f91-4223-8e27-bbfe4a81a601 - config: - collection-name: My collection name -``` +For information on how to publish to a specific collection or directly to Postman, see [Publishing to Postman](/products/sdks/overview/postman/publishing-to-postman.mdx). -If you'd like to publish to a particular collection, just specify the collection ID. -```yaml title="generators.yml" {10} -generators: - postman: - generators: - - name: fernapi/fern-postman - version: 0.4.0 - output: - location: postman - api-key: ${POSTMAN_API_KEY} - workspace-id: 07e228e5-3f91-4223-8e27-bbfe4a81a601 - collection-id: 21510182-14b07230-46e2-431e-8153-d5c7d217b214 - config: - collection-name: My collection name -``` diff --git a/fern/products/sdks/overview/postman/publishing-to-postman.mdx b/fern/products/sdks/overview/postman/publishing-to-postman.mdx new file mode 100644 index 000000000..d1a6d20e1 --- /dev/null +++ b/fern/products/sdks/overview/postman/publishing-to-postman.mdx @@ -0,0 +1,46 @@ +--- +title: Publishing to Postman +description: Publish a Postman collection full of example requests and responses +--- + +Publish your Postman collection directly to Postman workspaces, making it easy for your team and API consumers to discover and test your endpoints. + +## Publish directly to Postman + +To publish your collection directly to Postman, configure the output and specify the name of your collection: + +```yaml title="generators.yml" {6-9} +generators: + postman: + generators: + - name: fernapi/fern-postman + version: 0.4.0 + output: + location: postman + api-key: ${POSTMAN_API_KEY} + workspace-id: 07e228e5-3f91-4223-8e27-bbfe4a81a601 + config: + collection-name: My collection name +``` + +## Publish to a collection + +To publish to a particular collection, configure the output and specify the name of your collection and collection ID: + +```yaml title="generators.yml" {10} +generators: + postman: + generators: + - name: fernapi/fern-postman + version: 0.4.0 + output: + location: postman + api-key: ${POSTMAN_API_KEY} + workspace-id: 07e228e5-3f91-4223-8e27-bbfe4a81a601 + collection-id: 21510182-14b07230-46e2-431e-8153-d5c7d217b214 + config: + collection-name: My collection name +``` + + + diff --git a/fern/products/sdks/overview/postman/quickstart.mdx b/fern/products/sdks/overview/postman/quickstart.mdx new file mode 100644 index 000000000..ba9bee6e4 --- /dev/null +++ b/fern/products/sdks/overview/postman/quickstart.mdx @@ -0,0 +1,69 @@ +--- +title: Postman quickstart +description: "Generate a postman collection full of example requests and responses" +--- + +A Postman collection contains ready-to-use HTTP requests with example payloads and responses that developers can immediately test and explore in Postman. Each API definition generates one complete collection with all endpoints organized into folders. + +Generate a Postman collection by following the instructions on this page. + + + This page assumes that you have an initialized `fern` folder on your local + machine. See [Set up the `fern` folder](/sdks/overview/quickstart). + + + + + + +### Add the Postman generator + +Run the following command to add the Postman generator to `generators.yml`: + +```sh +fern add fern-postman --group postman +``` + + + `postman` is the name of the `generators.yml` group that configures your Postman collection's output location and other metadata. You can customize this group name to differentiate between multiple collections if you have multiple APIs in your organization. + + +This command adds the following `group` to `generators.yml`: + +```yaml title="generators.yml" {2-8} +groups: + postman: + generators: + - name: fernapi/fern-postman + version: 0.0.45 + output: + location: local-file-system + path: ../postman +``` + +### Generate the collection + +Run the following command: + +```sh +fern generate --group postman +``` + + + If you have multiple APIs, use the [`--api` flag](/cli-api-reference/cli-reference/commands#api) to specify the API you want to generate: + + ```bash + fern generate --group postman --api your-api-name + ``` + + +This creates a Postman collection on Fern's cloud. Once complete, you'll see a `collection.json`: + +```bash {4-5} +fern/ + ├─ fern.config.json + ├─ generators.yml +postman + ├─ collection.json +``` + \ No newline at end of file diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml index b3842290d..621bc99cf 100644 --- a/fern/products/sdks/sdks.yml +++ b/fern/products/sdks/sdks.yml @@ -179,6 +179,14 @@ navigation: slug: changelog - link: Customer showcase href: https://buildwithfern.com/showcase#sdk-customers.ruby + - section: Postman + contents: + - page: Quickstart + path: ./overview/postman/quickstart.mdx + slug: quickstart + - page: Publishing to Postman + path: ./overview/postman/publishing-to-postman.mdx + slug: publishing - page: MCP Server path: ./overview/mcp-server/introduction.mdx slug: mcp-server