Skip to content

Commit 62ea8b4

Browse files
devalogdevalog
authored
(sdks) Expand Postman publishing page (#999)
1 parent 95921ab commit 62ea8b4

File tree

6 files changed

+332
-13
lines changed

6 files changed

+332
-13
lines changed

‎fern/products/sdks/overview/postman/assets/api-key.png‎

215 KB
Loading

‎fern/products/sdks/overview/postman/assets/collection-success.png‎

174 KB
Loading

‎fern/products/sdks/overview/postman/assets/get-workspace-id.png‎

373 KB
Loading

‎fern/products/sdks/overview/postman/publishing-to-postman.mdx‎

Lines changed: 299 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,42 +5,328 @@ description: Publish a Postman collection full of example requests and responses
55

66
Publish your Postman collection directly to Postman workspaces, making it easy for your team and API consumers to discover and test your endpoints.
77

8-
## Publish directly to Postman
8+
<Frame>
9+
<img src="assets/collection-success.png" alt="Collection published on Postman" />
10+
</Frame>
911

10-
To publish your collection directly to Postman, configure the output and specify the name of your collection:
12+
<Info>
13+
This page assumes that you have:
1114

12-
```yaml title="generators.yml" {6-9}
15+
* An initialized `fern` folder. See [Set up the `fern`
16+
folder](/sdks/overview/quickstart).
17+
* A GitHub repository for your Postman collection. See [Project structure](/sdks/overview/project-structure).
18+
* A Postman generator group in `generators.yml`. See [Postman
19+
Quickstart](quickstart#add-the-sdk-generator).
20+
21+
</Info>
22+
23+
## Generate an API key
24+
25+
<Steps>
26+
27+
<Step title="Log into Postman">
28+
29+
Log into [Postman](https://www.postman.com/) or create a new account.
30+
31+
</Step>
32+
33+
<Step title="Navigate to API Keys">
34+
35+
1. Click on your profile picture.
36+
1. Select **Settings**.
37+
1. Select **API Keys**.
38+
39+
<Frame>
40+
<img src="assets/api-key.png" alt="Collection published on Postman" />
41+
</Frame>
42+
43+
</Step>
44+
45+
<Step title="Generate key">
46+
Click on **Generate API Key**. Name your key, then click **Generate**.
47+
48+
<Warning>Save your new token – it won't be displayed after you leave the page.</Warning>
49+
50+
</Step>
51+
52+
</Steps>
53+
54+
## Configure Postman publication
55+
56+
You'll need to update your `generators.yml` file to configure the output location, repository, publishing mode, and authentication credentials for Postman publishing. Your `generators.yml` [should live in your source repository](/sdks/overview/project-structure) (or on your local machine), not the repository that contains your Postman collection file.
57+
<Steps>
58+
<Step title="Configure `output` location">
59+
60+
In the `group` for your Postman collection, change the output location from `local-file-system` (the default) to `postman` to indicate that Fern should publish your collection directly to Postman:
61+
62+
```yaml {6-7} title="generators.yml"
63+
groups:
64+
postman: # Group name for your Postman collection
65+
generators:
66+
- name: fernapi/fern-postman
67+
version: <Markdown src="/snippets/version-number-postman.mdx"/>
68+
output:
69+
location: postman
70+
```
71+
72+
</Step>
73+
<Step title="Add repository location">
74+
75+
Add the path to the GitHub repository containing your Postman collection:
76+
77+
```yaml {8-9} title="generators.yml"
78+
groups:
79+
postman:
80+
generators:
81+
- name: fernapi/fern-postman
82+
version: <Markdown src="/snippets/version-number-postman.mdx"/>
83+
output:
84+
location: postman
85+
github:
86+
repository: your-org/company-postman
87+
```
88+
89+
</Step>
90+
<Step title="Choose your publishing mode">
91+
92+
Optionally set the mode to control how Fern handles Postman publishing:
93+
94+
- `mode: release` (default): Fern generates code, commits to main, and tags a release automatically
95+
- `mode: pull-request`: Fern generates code and creates a PR for you to review before release
96+
- `mode: push`: Fern generates code and pushes to a branch you specify for you to review before release
97+
98+
You can also configure other settings, like the reviewers or license. Refer to the [full `github` (`generators.yml`) reference](/sdks/reference/generators-yml#github) for more information.
99+
100+
```yaml {10} title="generators.yml"
101+
groups:
102+
postman:
103+
generators:
104+
- name: fernapi/fern-postman
105+
version: <Markdown src="/snippets/version-number-postman.mdx"/>
106+
output:
107+
location: postman
108+
github:
109+
repository: your-org/company-postman
110+
mode: push
111+
branch: your-branch-name
112+
```
113+
</Step>
114+
<Step title="Configure Postman API key">
115+
116+
Add `api-key: ${POSTMAN_API_KEY}` to `generators.yml` to tell Fern to use your API key for authentication when publishing to a Postman collection.
117+
118+
```yaml {8} title="generators.yml"
119+
groups:
120+
postman:
121+
generators:
122+
- name: fernapi/fern-postman
123+
version: <Markdown src="/snippets/version-number-postman.mdx"/>
124+
output:
125+
location: postman
126+
api-key: ${POSTMAN_API_KEY}
127+
github:
128+
repository: your-org/company-postman
129+
```
130+
</Step>
131+
</Steps>
132+
133+
## Choose your versioning approach
134+
135+
Fern's Postman publishing uses a simple versioning approach based on whether you specify a `collection-id`:
136+
137+
- **Update existing collection:** Specify `collection-id`. Fern updates the same collection each time. Use this option to keep your workspace clean with one collection that is always current.
138+
- **Create new collections:** Omit `collection-id`. Fern creates a new collection with each publish. Use this option to maintain historical versions or separate environment collections.
139+
140+
<AccordionGroup>
141+
<Accordion title="Publish as a new collection">
142+
<Steps>
143+
<Step title="Specify the workspace ID">
144+
<Markdown src="/products/sdks/snippets/postman-workspace.mdx"/>
145+
146+
</Step>
147+
<Step title="Specify the collection name">
148+
Set the name for your new collection. Each time you publish, Fern creates a new collection with this name in the specified workspace.
149+
150+
```yaml title="generators.yml" {10-11}
13151
groups:
14152
postman:
15153
generators:
16154
- name: fernapi/fern-postman
17-
version: 0.4.0
155+
version: <Markdown src="/snippets/version-number-postman.mdx"/>
18156
output:
19157
location: postman
20158
api-key: ${POSTMAN_API_KEY}
21-
workspace-id: 07e228e5-3f91-4223-8e27-bbfe4a81a601
159+
workspace-id: your-workspace-id
22160
config:
23-
collection-name: My collection name
161+
collection-name: My collection name # Creates new collection called "My collection name"
162+
github:
163+
repository: your-org/company-postman
24164
```
165+
</Step>
166+
</Steps>
167+
</Accordion>
168+
169+
<Accordion title="Publish to an existing collection">
170+
171+
To publish to a existing collection, specify the workspace ID, existing collection ID, and name of the existing collection.
25172

26-
## Publish to a collection
173+
<Steps>
174+
<Step title="Specify the workspace ID">
175+
<Markdown src="/products/sdks/snippets/postman-workspace.mdx"/>
27176

28-
To publish to a particular collection, configure the output and specify the name of your collection and collection ID:
177+
</Step>
29178

30-
```yaml title="generators.yml" {10}
179+
<Step title="Specify the collection name and ID">
180+
181+
You can get your collection name and ID by navigating to your workspace and either:
182+
- Copying the ID from the URL: `https://user-name.postman.co/workspace/workspace-name~workspace-id/collection/COLLECTION-ID`
183+
- Making a GET request to `https://api.getpostman.com/collections`. You must also enter your API key in the **Auth** tab. Send the request. This request returns configuration, including IDs and names, for all of your collections.
184+
185+
```yaml title="generators.yml" {10-12}
31186
groups:
32187
postman:
33188
generators:
34189
- name: fernapi/fern-postman
35-
version: 0.4.0
190+
version: <Markdown src="/snippets/version-number-postman.mdx"/>
36191
output:
37192
location: postman
38193
api-key: ${POSTMAN_API_KEY}
39-
workspace-id: 07e228e5-3f91-4223-8e27-bbfe4a81a601
40-
collection-id: 21510182-14b07230-46e2-431e-8153-d5c7d217b214
194+
workspace-id: your-workspace-id
195+
collection-id: your-collection-id
41196
config:
42-
collection-name: My collection name
197+
collection-name: Your collection name # Name of the existing collection
198+
github:
199+
repository: your-org/company-postman
43200
```
201+
</Step>
202+
</Steps>
203+
</Accordion>
204+
</AccordionGroup>
205+
206+
## Publish your collection
207+
208+
Decide how you want to publish your collection to Postman. You can use GitHub workflows for automated releases or publish directly via the CLI.
209+
210+
<AccordionGroup>
211+
212+
<Accordion title="Release via a GitHub workflow">
213+
214+
Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new Postman collection releases directly from your source repository.
215+
216+
<Steps>
217+
<Step title="Set up authentication">
218+
219+
Open your source repository in GitHub. Click on the **Settings** tab. Then, under the **Security** section, open **Secrets and variables** > **Actions**.
220+
221+
You can also use the url `https://github.com/<your-repo>/settings/secrets/actions`.
222+
223+
</Step>
224+
<Step title="Add secret for your API key">
225+
226+
1. Select **New repository secret**.
227+
1. Name your secret `POSTMAN_API_KEY`.
228+
1. Add the corresponding API key you generated above.
229+
1. Click **Add secret**.
230+
231+
</Step>
232+
<Step title="Add secret for your Fern Token">
233+
234+
1. Select **New repository secret**.
235+
1. Name your secret `FERN_TOKEN`.
236+
1. Add your Fern token. If you don't already have one, generate one by
237+
running `fern token`. By default, the `fern_token` is generated for the
238+
organization listed in `fern.config.json`.
239+
1. Click **Add secret**.
240+
241+
</Step>
242+
<Step title="Set up a new workflow">
243+
244+
Set up a CI workflow that you can manually trigger from the GitHub UI. In your repository, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Add a workflow that's similar to this:
245+
246+
```yaml title=".github/workflows/publish.yml" maxLines=0
247+
name: Publish Postman collection
248+
249+
on:
250+
workflow_dispatch:
251+
inputs:
252+
version:
253+
description: "The version of the Postman collection that you would like to release"
254+
required: true
255+
type: string
256+
257+
jobs:
258+
release:
259+
runs-on: ubuntu-latest
260+
steps:
261+
- name: Checkout repo
262+
uses: actions/checkout@v4
263+
264+
- name: Install Fern CLI
265+
run: npm install -g fern-api
266+
267+
- name: Release Postman collection
268+
env:
269+
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
270+
POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}
271+
run: |
272+
fern generate --group postman --version ${{ inputs.version }} --log-level debug
273+
```
274+
<Note>
275+
You can alternatively configure your workflow to execute `on: [push]`. See Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml) for an example.
276+
</Note>
277+
</Step>
278+
279+
<Step title="Regenerate and release your collection">
280+
281+
Navigate to the **Actions** tab, select the workflow you just created, specify a version number, and click **Run workflow**. This regenerates your collection.
282+
283+
<Note>
284+
Specifying the version number will update the release number in your GitHub repository, but won't version your collection.
285+
</Note>
286+
287+
<Markdown src="/products/sdks/snippets/generate-postman.mdx"/>
288+
289+
</Step>
290+
291+
</Steps>
292+
293+
</Accordion>
294+
295+
<Accordion title="Release via CLI and environment variables">
296+
<Steps>
297+
298+
<Step title="Set Postman environment variable">
299+
300+
Set the `POSTMAN_API_KEY` environment variable on your local machine:
301+
302+
```bash
303+
export POSTMAN_API_KEY=your-actual-postman-api-key
304+
```
305+
306+
</Step>
307+
<Step title="Regenerate and release your collection">
308+
309+
Regenerate your collection.
310+
311+
<Note>
312+
The `--version` parameter in `fern generate --version X.X.X` creates a GitHub release tag but doesn't affect Postman collection naming or versioning. Collection versioning is controlled by the `collection-id` configuration.
313+
</Note>
314+
315+
```bash
316+
fern generate --group postman --version <version>
317+
```
318+
319+
<Markdown src="/products/sdks/snippets/generate-postman.mdx"/>
320+
321+
</Step>
322+
323+
</Steps>
324+
</Accordion>
325+
</AccordionGroup>
326+
327+
328+
329+
44330

45331

46332

‎fern/products/sdks/snippets/generate-postman.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
The rest of the release process depends on your chosen mode:
2+
3+
- **Release mode (default):** If you didn't specify a `mode` or set `mode: release`, no further action is required. Fern initiates the publishing workflow in your collection repository.
4+
5+
- **Pull request or push mode:** If you set `mode: pull-request` or `mode: push`, Fern creates a pull request or pushes to a branch respectively. Review and merge the PR (`pull-request`) or branch (`push`), then [tag a new release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) to initiate the publishing
6+
7+
Once the workflow completes, you can view your new or updated collection by logging into Postman and navigating to your workspace.
8+
9+
<Frame>
10+
<img src="assets/collection-success.png" alt="Collection published on Postman" />
11+
</Frame>

‎fern/products/sdks/snippets/postman-workspace.mdx‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
You can get your workspace ID by navigating to your workspace and either:
2+
3+
- Copying the ID from the URL: `https://user-name.postman.co/workspace/workspace-name~WORKSPACE-ID/request/create`
4+
- Making a GET request to `https://api.getpostman.com/workspaces`. You must also enter your API key in the **Auth** tab. This request returns configuration, including IDs, for all of your workspaces.
5+
6+
<Frame>
7+
<img src="assets/get-workspace-id.png" alt="Collection published on Postman" />
8+
</Frame>
9+
10+
```yaml title="generators.yml" {9}
11+
groups:
12+
postman:
13+
generators:
14+
- name: fernapi/fern-postman
15+
version: 0.4.0
16+
output:
17+
location: postman
18+
api-key: ${POSTMAN_API_KEY}
19+
workspace-id: your-workspace-id
20+
github:
21+
repository: your-org/company-postman
22+
```

0 commit comments

Comments
 (0)