I am no stranger to working up and down the stack. To me, it’s part of the challenge, and I love a complex chunk of work. I will choose stories in the backlog requiring parallel frontend and backend changes just for fun. Lately, I have come to appreciate how simple tools like Swagger make it to integrate API changes into your UI. Specifically, Swagger Codegen enables developers to generate an NPM package that contains all data shapes an endpoint uses. This is especially convenient for data shaping and schema consistency between the two ends.
What Is Swagger?
Swagger is a set of tools visualizing and providing easy access to an API. It auto-generates documentation for the backend. Swagger behaves like a visual blueprint, informing the user of what endpoints exist and what data each one accepts/receives. As a result, developers are able to quickly determine the “contract” needed to properly use their API. Typically, C# and Node projects are compatible with these tools. In this instance, we will focus specifically on Swagger Codegen.
Swagger Codegen is a tool that generates an NPM package for use on your frontend. This NPM package contains methods that will submit requests to your API without needing to use tools like Axios. Going further, each of these endpoints binds with types acting as the schema for the data moving between the API. In an instance where the stack is rapidly changing, this package proves instrumental in maintaining data shape integrity.
How Does It Know The Datashape?
When creating an API using Swagger tools, you will usually have a controller layer that contains all of your endpoints. These endpoints return data, and that endpoint learns the data shape based on the return type. For example, returning an integer will associate the endpoint with an integer type.
When the API compiles, Swagger will then generate a JSON document. This JSON file contains all endpoints and the shape of every endpoint’s returned data inside of a JSON object. On package generation, the very first step Swagger Codegen will take is to read this JSON file. After reading the file, it will note all of the types and recreate them within the compiled package. From here, you install the package and reference the types from the node_modules directory.
How Do I Create An NPM Package Using Swagger Codegen?
To begin with, ensure you have Java installed. You will download a Swagger Codegen .jar file, but it will require Java and will not run without it.
Next, download a Swagger Codegen .jar file. There are different versions, but for OpenAPI based interfaces, use the 3.0+ version provided on Maven. Once downloaded, save it in a convenient location on your machine and note the path.
Now, run the following command:
java -jar "<path to your Swagger Codegen Jar file>" generate -D io.swagger.v3.parser.util.RemoteUrl.trustAll=true -i <URL to your Swagger JSON file> --additional-properties <additional options, if there> -l <type of client generating for> -o <output location>
To dissect this command:
- Everything before “-D” is calling the Codegen CLI using Java, requesting it to generate a package
- The “-D” trustAll argument enables Swagger Codegen to read from an HTTPS URL
- The “-i” is a URL pointing at your swagger.json document
- “–additional-properties” represents options you can use with Swagger Codegen
- “-l” represents the client type, and can represent multiple frameworks. Check the documentation for a list
- “-o” represents the output location of your generated code
Note your output location.
Once successful, change directories into the location of the output folder. First, do an npm install, and then run the command npm run build <project/package name>.
Lastly, if the package builds successfully, enter the dist folder and then run npm pack. This will create a tarball of your API’s controller layer that you can use on your frontend framework. Now it’s as simple as returning to your frontend project’s root directory and running npm install .
And that’s it! Now you can use your generated API package on your frontend and use generated types. Remember to redo this process every time you make an update to your API. This is to keep your package updated correctly.