In modern software development, having well-documented APIs is crucial for collaboration and integration. Postman is a popular tool for testing and documenting APIs. Open API Specification is a widely accepted standard for defining RESTful APIs. In this blog post, we'll walk you through the process of converting a Postman collection into an OpenAPI specification and then using the OpenAPI Generator to create a JavaScript client from it.
There are 2 different ways to approach API development.
-
Design First: Postman -> Swagger/Open Api Spec -> Code
-
Code First: Code -> Postman Code -> Swagger
In this blog post, we will explore the 'Design First' approach to API development.
Design First Vs Code First - High level differences
| Aspect | Design First Approach | Code First Approach |
|---|---|---|
| Initial Project Concept | Requires a clear understanding of project goals and requirements from the start. | Allows for a more flexible approach, where the initial project concept may not be well-defined. |
| Team Composition | Involves a cross-functional design team, including architects and designers. | Relies on a team of developers, testers, and domain experts who can adapt to changing requirements. |
| Starting Point | Begins with a detailed design and specification of the software system. | Starts by writing code to create a basic functional prototype or MVP. |
| Flexibility | May lead to more rigid development, with a focus on adhering to the initial design. | Offers greater adaptability to evolving requirements and allows for frequent changes. |
| Feedback Gathering | Feedback is primarily gathered during the design and specification phase. | Feedback is collected continuously throughout the development process based on the evolving codebase. |
| Documentation | Detailed design documentation is created before implementation. | Documentation is created as the design and specifications emerge during development. |
| Testing and Quality Assurance | Testing is performed against the well-defined design. | Testing is integrated throughout the development process to ensure code quality. |
| Stakeholder Involvement | Stakeholder involvement primarily during design and specification phases. | Continuous stakeholder involvement and feedback are encouraged throughout development. |
| Refactoring and Optimization | Design changes are costly and may require significant rework. | Code is refactored and optimized as needed to maintain quality and adapt to changing requirements. |
| Initial Deployment | Deployment may occur later in the development process. | Allows for continuous deployment of prototypes and updates to gather real-world feedback. |
| Ongoing Maintenance | Maintenance activities are largely predictable based on the initial design. | Ongoing maintenance is essential, with a focus on adapting to evolving needs and addressing emerging issues. |
Both approaches have their advantages and are suited to different project scenarios. The choice between "Design First" and "Code First" depends on the project's specific requirements, goals, and constraints.
Convert a Postman Collection to a Swagger Specification
There are several methods to convert a Postman collection to a Swagger Specification. In this section, we'll discuss some of the most popular ways to accomplish this task:
-
Swagger Editor: One of the most common methods is to use the Swagger Editor. This web-based tool provides a user-friendly interface for creating and editing Swagger specifications. It allows you to manually convert your Postman collection into a Swagger Specification by copy-pasting the relevant information.
-
Stoplight Studio: Another excellent option is Stoplight Studio, an integrated development environment for designing and documenting APIs. Stoplight Studio provides features that can help streamline the process of converting a Postman collection to Swagger.
-
npm Package: If you prefer a programmatic approach, you can explore various npm packages and libraries that are designed to automate the conversion process. These packages often provide command-line tools and scripts to convert your collection to a Swagger Specification, making the process more efficient.
Each of these methods has its advantages and is suitable for different use cases. You can choose the one that best fits your workflow and requirements.
However, for the purpose of this demo, we are showing how to perform the conversion through the npm Package.
Step 1: Installing the "postman-to-openapi" Package
The first step is to install the "postman-to-openapi" package, which allows you to convert Postman collections to OpenAPI specifications. To do this, open your terminal and run the following command:
npm i postman-to-openapi -g
-
npm: This is the Node Package Manager, a package manager for JavaScript that is commonly used to install and manage libraries and tools.
-
i: This is short for "install," and it's the npm command used to install packages.
-
postman-to-openapi: This is the name of the package you want to install.
-
-g: This flag stands for "global," and it tells npm to install the package globally on your system, making it available as a command-line tool that you can run from any directory.
This command uses the Node Package Manager (npm) to install the package globally on your system. Once installed, you'll be able to use the "postman-to-openapi" command as a command-line tool.
Step 2: Converting Postman Collections to OpenAPI Specifications
Now that you have "postman-to-openapi" installed, you can convert your Postman collections to OpenAPI specifications. Replace ~/Downloads/REST_API.postman_collection.json with the path to your Postman collection and specify where you want to save the resulting OpenAPI specification. Use the following command:
p2o ~/Downloads/REST_API.postman_collection.json -f ~/Downloads/open-api-result.yml
-
p2o: This is the command you use to run the postman-to-openapi tool. It is installed globally on your system using npm i postman-to-openapi -g, as mentioned earlier.
-
~/Downloads/REST_API.postman_collection.json: This is the path to your Postman collection file. You should replace this with the actual file path to your Postman collection that you want to convert.
-
-f: This flag is used to specify the output format of the converted OpenAPI specification.
-
~/Downloads/open-api-result.yml: This is the path where the resulting OpenAPI specification will be saved as a YAML file. You should replace this with the desired file path where you want to save the OpenAPI specification.
This command will take your Postman collection, process it, and save the resulting OpenAPI specification as a YAML file. Ensure that you provide the correct file paths.
Covert Open Api spec to Javascript code
Step 1: Configuring Your Java Environment
If you plan to generate code from your OpenAPI specification, you'll need a Java environment set up. Use the following commands to set the JAVA_HOME environment variable and update the PATH:
export JAVA_HOME=/usr/lib/jvm/java-1.11.0-openjdk-amd64
export PATH=$JAVA_HOME:$PATH
-
export JAVA_HOME=/usr/lib/jvm/java-1.11.0-openjdk-amd64: This command sets the JAVA_HOME environment variable to the specified directory, which is typically the root directory of a specific JDK version. In this case, it appears to be pointing to the root directory of OpenJDK 11.
-
export PATH=$JAVA_HOME:$PATH: This command appends the JAVA_HOME directory to the beginning of the PATH environment variable. The PATH variable is a list of directories where the system looks for executable files, so adding the JAVA_HOME directory to the PATH allows you to easily run Java-related commands and tools.
These commands are essential for Java development and ensure that the correct Java version is used in your development environment.
Step 2: Generating JavaScript Code from OpenAPI
To complete our journey, we'll use the OpenAPI Generator CLI to generate code from our OpenAPI specification. First, download the CLI JAR File file using wget:
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.0.1/openapi-generator-cli-7.0.1.jar -O openapi-generator-cli.jar
-
wget: This is the command-line tool used for downloading files from the internet.
-
https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.0.1/openapi-generator-cli-7.0.1.jar: This is the URL of the JAR file you want to download.
-
-O openapi-generator-cli.jar: This part of the command specifies that you want to save the downloaded file with the name openapi-generator-cli.jar.
This command uses wget to download the CLI JAR file and renames it as openapi-generator-cli.jar.
Finally, run the OpenAPI Generator CLI to create code from your OpenAPI specification:
java -jar ./openapi-generator-cli.jar generate -i ./open-api-result.yml -g javascript -o ./nodejs_api_client
-
java -jar ./openapi-generator-cli.jar: This part of the command runs the Java JAR file (openapi-generator-cli.jar) using the java command. The JAR file is responsible for generating code from the OpenAPI specification.
-
generate: This is a command provided by the OpenAPI Generator CLI to instruct it to generate code based on the OpenAPI specification.
-
-i ./open-api-result.yml: This flag specifies the input OpenAPI specification file. In this case, it's using the file named open-api-result.yml.
-
-g javascript: This flag specifies the target generator. In this case, it's generating JavaScript code.
-
-o ./nodejs_api_client: This flag specifies the output directory where the generated code will be placed. In this case, the code will be generated in a directory called nodejs_api_client in the current working directory.
This command invokes the CLI JAR.
In summary, these are the steps guide you through converting a Postman collection into an OpenAPI specification and then generating code from that specification. It's a streamlined process that aids in API development and documentation. By following these commands and tools, you can enhance your development workflow and collaboration.