Skip to main content

Postman Collections

Follow this tutorial if:

  • You don't have an OpenAPI Spec (OAS)
  • You are using Postman Collections
caution

The output of konfig p2o is low quality and should not be used to publish SDKs. To ensure Konfig can generate high quality SDKs you must make sure your OAS passes Konfig's linter. Follow directions on how to run Konfig's linter here and quickly fix your OAS

1. Save Example Responses in Postman​

Example responses are needed for automatically generating OpenAPI schemas with konfig fix. Do the following 4 steps for all your endpoints before exporting.

tip

The more examples your provide the better quality your OpenAPI Specification will be. Especially if you are running the output through konfig fix as we use the examples to determine your schemas.

a) Send Request​

Click Send to retrieve an example response. You can do repeat these steps for diferent inputs to save multiple example responses.

Save Postman Response

b) Click "Save Response"​

Open the menu for saving the response.

Save Postman Response

c) Click "Save as example"​

Save the retrieved response as an example in your collection.

Save Postman Response

d) Example should be shown in menu​

You should see a list of examples saved in the left-side menu.

Save Postman Response

2. Export Postman Collection to JSON​

Click the settings for the target Postman Collection and click "export":

Export Postman

Choose Collection v2.1 and click Export.

Export Postman Button

3. Setup Konfig CLI​

Ensure you have the konfig-cli installed by running


_10
npm install -g konfig-cli

4. Convert Exported Postman Collection to OpenAPI Spec​

Once you have exported your collection to a .json file you can not convert it to an OAS .yaml file.

To do this simply run:


_10
konfig p2o -p <path_to_your_exported_postman_collection>.json -o oas.yaml

You will see an output that looks something like this:

Example Output

_55
openapi: 3.0.0
_55
info:
_55
title: Slack Web API
_55
version: 1.0.0
_55
servers:
_55
- url: http://{{baseurl}}
_55
components:
_55
securitySchemes:
_55
bearerAuth:
_55
type: http
_55
scheme: bearer
_55
security:
_55
- bearerAuth: []
_55
tags:
_55
- name: Admin API
_55
description: >-
_55
Use approval and provisioning APIs to help Slack Admins work more
_55
effectively.
_55
# ... unnecessary details omitted
_55
paths:
_55
/admin.users.setOwner:
_55
post:
_55
tags:
_55
- Admin API
_55
summary: admin users set Owner
_55
description: >-
_55
Set an existing guest, regular user, or admin user to be a workspace
_55
owner.
_55
requestBody:
_55
content:
_55
application/x-www-form-urlencoded:
_55
schema:
_55
type: object
_55
properties:
_55
team_id:
_55
type: string
_55
description: The ID (`T1234`) of the workspace.
_55
example: <string>
_55
user_id:
_55
type: string
_55
description: Id of the user to promote to owner.
_55
example: <string>
_55
parameters:
_55
- name: token
_55
in: header
_55
schema:
_55
type: string
_55
description: "(Required) Authentication token. Requires scope: `admin.users:write`"
_55
example: <string>
_55
- name: Content-Type
_55
in: header
_55
schema:
_55
type: string
_55
example: application/x-www-form-urlencoded
_55
# ... unnecessary details omitted