APIs play a crucial role in today’s connected world. Almost every app on your mobile device is backed by an API. For the same reason, API development has become a trending topic nowadays. There are lots of standards that have become popular in the API development space. One such standard is the format of API specification documents. OpenAPI Specification (formerly known as Swagger) has become the de facto format of describing APIs in the modern API world. There are also many great tools built around it to facilitate API development and API lifecycle management. In this article, we’re going to discuss the importance of OpenAPI specification and 3 great OpenAPI tools that can make your API development lifecycle productive and efficient.
The most challenging aspect of API Development
There are 2 main parties in the API ecosystem, the API publishers and the API consumers. The API publisher exposes an API and the API consumer consumes it. However, the API itself is not the only thing that the API publisher provides to the API consumer. There are other related products such as API docs, SDKs, Postman Collections, etc. So every time something changes in the API, the API publisher has to update all these related products as well. And, it can be very hard to manually track all these changes and update accordingly. On the other hand, if you own a lot of APIs, manually updating all these may not be scalable as well . What if you had a way to automate this process? What if every time you change your API, all the downstream products mentioned above are updated automatically? Sounds amazing, isn’t it? It’s actually possible. All you need is a source of truth for your API. This is where OpenAPI files (or OAS definitions) come into action.
How OpenAPI files can save the day
What does it mean that OpenAPI files can be the source of truth of your API? That’s simple. You simply start your API with an OpenAPI file. That’s what’s called “API-first development”. Once you have your OpenAPI file ready, then you generate everything else from it. There are many tools available that can generate API docs, SDKs, Postman Collections etc. from OpenAPI files. But what about the actual implementation? The good news is you can even generate the API implementation, partially. Basically what you generate is the skeleton of your API implementation. If you are a Java developer, what you generate is a couple of Java interfaces and a set of model classes. Then, all you have to do is implement those interfaces. That means your code base has 2 kinds of code, generated code and manually written code. What about the changes? If you want to make any change to your API contract, you do that to the OpenAPI file and generate your code again. It replaces the generated code but does not touch your manually written code. You may have to update some manually written code parts to match the newly generated changes. That’s it. That’s how API-first approach works.
OpenAPI tools to make your life easier
There are many great tools covering different aspects of OpenAPI files. That includes tools that generate code, generate docs, generate SDKs, generate tests, etc. Such tools are usually very popular because they cover very common use cases. So, you can easily find so much information about such tools on the internet. Therefore, we’re not going to talk about those that cover the most common use cases. Instead, we’re going to talk about 3 great OpenAPI tools that are not so popular but can be essential to the API development lifecycle.
Spectral: OpenAPI Linter Tool
We discussed how the API-first approach makes life easier for API developers. However, defining and updating OpenAPI files can be very hard due to possible syntactic and semantic errors unless we have a proper validation mechanism that can validate every OpenAPI file we write and update. This is where the Spectral linter tool comes in handy.
Spectral is an open-source linter tool for OpenAPI files. It has a set of inbuilt rules to ensure the validity of OpenAPI files. This default ruleset represents the OpenAPI Specification (OAS) which defines what an OpenAPI file is, what it should look like, what it can do, how it can be extended, etc. In addition to that, you can define your own custom Spectral rules as well to validate additional rules you want to enforce, for example, your company’s internal REST API design guidelines.
Here are some default rules that are very useful in the day to day API development.
- API endpoints should not be ambiguous, which means there should not be multiple overlapping API endpoints.
- OpenAPI files should have “Servers” defined.
- API request and response payload examples given in an OpenAPI file are valid as per the API models defined in the OpenAPI file itself.
- Given examples should be linked to at least one of the API endpoints
As mentioned before, in addition to default rules you can define your own custom rules as well. For example, there can be organisation-specific API guidelines that you want to enforce on your organisation’s APIs. The following are some examples.
- Path parameters, query parameters etc. should be in camel-case.
- Every request and response model should have examples.
- Every API endpoint should have one or more security schemes assigned.
- Enum values should be duplicated
Here is how you can define a custom spectral rule. This custom rule says that APIs must always have a description defined in their info object.
rules:
info-description:
given: $.info
then:
field: description
function: truthy
In addition to defining your own rules, you can even modify default rules as well. One way to do that is, you change the severity of default rules. For example, you can change a default “error” level rule to “warning”. Or you can even turn off default rules completely.
Spectral lets you define a hierarchy of rule files where one rule file can be overridden by another. In this article, we’re not going to discuss that in detail. There will be a separate article soon on Spectral alone that goes deep into its features.
Here are some important links of Spectral.
- Website
- Source code
- Documentation
Spectral supports OpenAPI Specification v2.0, v3.0, and v3.1 versions.
If you’re a user of WSO2 API Manager, there is good news for you. WSO2 API Manager now supports Spectral out of the box from APIM 4.2.0 onwards.
OpenAPI Diff Tool
OpenAPI diff tool is another great open-source OpenAPI tool. It lets you see the difference between 2 APIs. This is mostly important when you want to see the difference between 2 versions (or revisions) of the same API.
OpenAPI diff tool comes as a CLI as well as a Java library. When you run the tool, all you have to provide is the two input OpenAPI files that you want to see the diff between, and then it gives you the diff in a nice format. You can pick the output format as well. It supports HTML, Json, and Markdown (.md).
Here is an example usage of the CLI which tells it to generate the difference between `newsapi_v5.yaml` and `newsapi_v6.yaml` files, and write it into a file named `newsapi_diff_v5_v6.md` in the markdown format.
openapi-diff /specs/newsapi_v5.yaml /specs/newsapi_v6.yaml --markdown /output/newsapi_diff_v5_v6.md
The output mainly contains the following sections.
- New endpoints
- Deleted endpoints
- Deprecated endpoints
- Changed endpoints
- Changed extensions
- Changed elements
- Breaking (backwards-incompatible) changes
- Non-breaking (backwards-compatible) changes
Now, let’s discuss some practical use cases of the diff tool.
As an API developer, when you are about to release a new version of your API, you might need to prepare release notes as well. And you might even need to prepare a “what’s new” page as well. In those documents, you have to include API contract changes as well as functional changes of the API. The OpenAPI diff tool can be very helpful with generating all the contract changes you have in the new API version.
Another important use case of the OpenAPI diff tool is coming from its ability to detect breaking changes. When you release minor versions of your API, you must ensure that they don’t introduce any breaking (backwards-incompatible) changes. Otherwise, it can break your client integrations/applications which you need to avoid at all costs. So having a tool in the API development process for early detection of breaking API changes can make your life easy. The OpenAPI diff tool is smart enough to recognise if a detected change is a breaking change or not. The CLI tool has the inbuilt option “–fail-on-incompatible” for this purpose.
While the CLI tool is very simple to use, if you’re using the Java library of the tool, you can even do more custom things by extending its capabilities. Whether to use the CLI tool or the Java library should be decided based on whether you want simplicity and flexibility.
Here are some important links to the OpenAPI diff tool.
As per official documentation, the OpenAPI diff tool only supports the OpenAPI Specification v3.0 version. However, as per some discussions in its git repo, it might even support the OpenAPI v3.1 version as well in its current state, even though it’s not directly claimed in its official docs.
OpenAPI Merge Tool
This is another great OpenAPI tool which gives you the ability to merge multiple OpenAPI files into one. This tool is useful when multiple teams develop related APIs (e.g., microservices), and you want to expose them collectively to users.
The OpenAPI Merge tool’s job is very straightforward. It requires 2 or more OpenAPI files as inputs and it simply merges them and outputs as a single OpenAPI file. However, unlike the previous 2 tools we discussed, the OpenAPI Merge tool requires a configuration file which defines the paths to input and output files. Here is a sample configuration file.
Sometimes, merging OpenAPI files can be complicated because the given input files can have the same or similar resources and models. Merging such files can cause merge conflicts. OpenAPI Merge tool handles such conflicts in 2 ways.
- If both OpenAPI files have the same model schema, they are treated as the same, and only one of them is copied to the output file. Then that is referred to by the other components copied from both input files.
- If the schema name is the same but their properties are different in 2 input files, they can’t be treated as the same model. In that case, both models should go to the output file, but they can’t have the same name. This requires renaming one of the conflicting model schema names. In such cases, the tool requires help from a domain expert such as the API developer to decide which OpenAPI file should get priority. So the tool expects the developer to tell the tool that models of which input OpenAPI files should be renamed in a conflict and how they should be renamed. The good thing is that this can be pre-configured in the tool’s configuration file. You can configure components of which input OpenAPI files should be renamed and with what prefix or suffix. The below is a sample config.
That’s just one main feature of this tool. Below are some other important features.
- Prefixes and suffixes can be added to given OpenAPI files regardless of conflicts.
- Endpoints can be selected or dropped based on their tags.
- Path modifications can be done by stripping and prepending parts.
- OpenAPI file info-descriptions can be merged together, or a completely new description can be set in the merged output file.
Here are some important links to the OpenAPI merge tool.
Currently, the OpenAPI Merge tool only supports the OpenAPI Specification v3.0 version. OpenAPI v3.1 support is yet to come.
Conclusion
In this article, we discussed how important OpenAPI files are for API development lifecycle and how OpenAPI tools facilitate better and easier use of OpenAPI files. Most importantly, 3 great OpenAPI tools were introduced in this article, that are Spectral linter tool, OpenAPI diff tool, and OpenAPI merge tool. We discussed what problems each of these tools solves, how to use them, and what their main features are. So, if you’re an API developer, a product manager, or anyone working in API development, this article could be a valuable resource. Now, go ahead and try these excellent tools: it will pay off in the long run of your API journey.