Finally a readable API Spec for both human and machine — OpenAPI (Swagger) Specification
Background
How often do we have to deal with integration with third party APIs? I probably spent about 50% - 60% of my time integrating with someone else’s APIs and in some industries you could be spending up to 90% of your time integrating with someone else’s ready-to-go product. In this post I’ll be sharing some of the common issues I’ve faced before I discovered OpenAPI (or commonly known as Swagger) and how OpenAPI helped to resolve them.
Problems
If the word document below looks familiar to you then you can probably sympathize with me. How many hours I spent in the past writing API specifications, how many copies and revisions I kept in the folder, and how I struggled to choose which template to use.
The below API is poorly written but it reflects what I had to deal with.
Perhaps you could argue that it’s just an issue with improper formatting and that if you choose the right template and with proper formatting like the example below, you could still have a clear API specification for others to integrate with.
But the below problems still persist:
- Extremely time consuming. It takes forever to write these specifications. If you put your documentation on the web, I wonder how much more work it would take to format everything.
- Inefficient and painstaking. It takes much manual effort to implement the API from these specs. It’s very tiring to go back and forth between your IDE and the browser.
- Inconsistency in formatting, there’s no universal standard and everyone has their own styles of writing them.
- Document and code not aligned. Because it’s manual there will be times when either the producer or the consumer’s code is not aligned with the document.
- Reduntancy. It’s repetitious to have your written code and a specification since your code is supposed to be the same as your specification.
OpenAPI to the rescue
OpenAPI allows you to write the specification that can be used to generate code stubs. That means as you’re writing the spec, you’re actually writing the code at the same time. The API spec that you write becomes the single source of truth. Whether you’re the producer or the consumer of the API, you can use the spec to generate the code stub. You no longer need to write all those boiler plate code yourself. The code and the document will never be inconsistent ever again.
This is what the OpenAPI generated documentation looks like:
As you can see all the API can be grouped and listed nicely in the Swagger UI.
If you expand any of the API you will be able to see the details for each API, what the request needs (whether request json, query params, or headers) and what the sample response will be. There’s also a “Try it out” button where you can actually send a real request to this API.
After you click the “Try it out” button, you can enter into the required parameters on the UI and when you click “Execute”, it’ll generate a curl statement for you and depending on your setup you can actually send the request out to the specified URL.
Of course in this case I’m just testing a random API so I have a 500 in response but I think you get the point.
Try it out with online editor
I myself use https://swagger.io/tools/swaggerhub/ to create the openAPI specification. There are built in intellisense and error checking with the online editor for swagger hub. Also as you’re typing, the swagger UI is generated real time so you can check in real time whether your syntax is correct and if the API spec is correct.
There are many OpenAPI samples on the internet for you to reference on.
Contract First Approach
In my previous project where OpenAPI was used we usually defined the contract up front. Once the contract was defined, both the producer and the consumer can work in parallel using the code generated directly from the contract definition. If any changes need to be made on the contract, all you need to do is to regenerate the code stub once more and make the necessary changes.
It’s a contract afterall
The contract is great but no contracts are effective unless both parties honor it. It’s best for the API producer to adapt OpenApi. I understand that it can be beneficial in terms of saving lines after lines of boiler plate code for the consumer, but if the producer doesn’t honor the contract, there’s no way for the consumer to know whether the contract matches the actual API. So if you’re the consumer and you want to write a contract for the sake of making things easier, you need to know the risks that you’re taking.
In the next post I’ll walk you through on how to use the OpenAPI Yaml spec to generate the code stub for both consumers and producers.
https://theochiu2010.medium.com/step-by-step-openapi-swagger-setup-6902ff93efbe
