Getting Started with Postman Collections
Postman is a great way to document and save example requests for your API. Konfig supports generating SDKs from Postman Collections through the Postman Collection Format. In this tutorial, we will walk through the steps for you to generate a TypeScript, Java, and Python SDK from a Postman Collection.
How does it work?
Konfig infers the interface of your API from request and response examples in your Postman Collection. Konfig then intelligently creates a high-quality OAS which is then used to generate SDKs.
To install Konfig's CLI run the following command:
Konfig's CLI requires Node 14+ to be setup on your machine.
Create a directory for SDKs
Prepare your Postman Collection
Every operation in your Collection should have more example responses saved before exporting for better SDKs.
Organize requests into folders
Placing requests under folders will help Konfig group operations together in the generated SDKs.
Parameterize request paths
Hard-coded values for variables such as path parameters will not be correctly
inferred as variables in the generated SDKs. For example, if you have a request
/project/1234, the SDKs will not know that
1234 is a variable.
Send to retrieve an example response. You can repeat these steps for
different inputs to save multiple example responses. The more requests and
responses saved in the Collection, the better your SDKs will be.
Click "Save as example"
Save the retrieved response as an example in your collection.
Example should be shown in the menu
You should see a list of examples saved in the left-side menu. Repeat this process for all your operations with as many examples as possible.
[required] to description of required parameters
For any required parameters, add
[required] to the description. This will
ensure that the SDKs will throw an error if the required parameter is not
Set preview language of response body
Set the preview language of the response body to
Text to ensure that
the response body schema type is inferred correctly in the generated SDKs. If
you want a raw string to be returned from your endpoint then thoose
you want the response body to be inferred an "object" type schema, then choose
Export Postman Collection
Click the button on your Postman Collection and click "export":
Collection v2.1 and click
Initialize SDK directory
Move the exported Postman Collection to the SDK directory
Copy yourto your .
Convert your Postman Collection to an OpenAPI Specification
command to convert to an OpenAPI
command to create your
Konfig will download the necessary setup files and ask a series of questions to
fill in your
konfig.yaml file. When , select
TypeScript for this tutorial.
Once finished, you will see a bunch of files automatically added to your directory.
_14tree -a_14._14├── .konfig_14│ ├── ruleset-version_14│ └── ruleset.js_14├── .spectral.yaml_14├── .vscode_14│ ├── extensions.json_14│ └── settings.json_14├── Requests.postman_collection.json_14├── api.yaml_14└── konfig.yaml_14_142 directories, 8 files
konfig.yaml file includes all the necessary configurations to generate SDKs for your Postman Collection. You can read more about the schema of
Create high-quality OAS
fix command to
create a high-quality OAS. This will override your OAS with a new version that
is prepared for generating high-quality SDKs.
You will be asked a series of questions regarding what to name particular operations and how to group them.
konfig generate to generate SDKs.
You will see the following output when generating SDKs.
It can take a few minutes to finish generating SDKs.
_14Output directory set to: /tmp/konfig-sdks-out_14Generating java, python, typescript SDKs... done_14Downloading 3 SDKs... done_14Deleting output directory... done_14Creating output directory... done_14Extracting SDKs... done_14Deleting contents of existing directory "java"... done_14Copying Java SDK to "java"... done_14Deleting contents of existing directory "python"... done_14Copying Python SDK to "python"... done_14Deleting contents of existing directory "typescript"... done_14Copying Typescript SDK to "typescript"... done_14Generating top-level README.md... done_14Writing top-level LICENSE... done
Once finished, you should see three SDKs added to your directory.
You can explore the example output of this tutorial here: https://github.com/konfig-dev/postman-getting-started-sdks.
To update your SDKs simply repeat the steps from export to generation.
Konfig's SDKs are highly customizable in case you need to add to your SDKs. Once you are finished developing your SDKs, you can also test, publish, and automate your entire SDK workflow with Konfig.