Spring GDS 25th Anniversary
A logistics company that ships to 190 countries built something to ship to itself.
OpenAPI (Swagger)
What is OpenAPI?
OpenAPI is a standard, machine-readable way to describe a REST API. One file, written in YAML or JSON, lists every endpoint, the parameters they take, the shape of each request and response, the auth they require, and the errors they can return. Swagger was the original name. When the spec was donated to the Linux Foundation it became OpenAPI, and the Swagger name now refers to the tooling built around it.
The point is a single source of truth that both humans and machines can read. From one OpenAPI document you can generate interactive documentation, client SDKs in a dozen languages, server stubs, mock servers, and contract tests. Two teams can agree on the spec first, then build the frontend and backend in parallel against it. A payments integration, for example, can be wired up and tested against a generated mock long before the real service is finished.
There are two ways to work. Design-first means you write the spec by hand and the code follows it. Code-first means you annotate your code and the spec is generated from it. Design-first keeps the contract honest because the API is agreed before anyone commits to an implementation. Either way, the spec stops being documentation that drifts out of date and becomes the thing the system is checked against.
OpenAPI at Dallonses
We work API-first, and OpenAPI is how we keep that promise concrete. On most projects the spec exists before the endpoints do. We agree the contract with the client and their other vendors, generate the mock and the docs, and let frontend and backend teams move in parallel without blocking each other. When the real implementation lands, contract tests check it against the same spec, so the API that ships matches the one everyone signed off on.
For API integration work, a clear OpenAPI document is what makes the difference between a clean handoff and weeks of guesswork. We hand clients a spec their own engineers can read, plug into their tooling, and trust. That is what an API first development approach buys: systems that connect cleanly because the contract was written down and held to, not described in a thread somewhere.
Building an API that other teams need to trust and connect to? Let's spec it right.
Related services
Related works
Vizitio
Turning a brand into a working business.
Access Ticket
Half a million people. One app. Zero chaos.
Ready to work together?
Book a meeting
