Swagger 3.0 Release Approaching – InApps 2022

The Swagger 3.0 team is currently aiming to have their tools updated to support the OpenAPI 3.0 specification within the next few months. Within that update will be the expanded ability to describe more complicated APIs and the ability to describe out of band requests. This is also the first major release of the OpenAPI specification as its own entity, aside from the Swagger toolchain.

How Swagger came about: In 2010, Tony Tam tried tackling some truly terrible technology troubles. As the API developer for a four-person startup, he was going nuts trying to keep his documentation up to date with his implementations. The work was constant, and eventually, one sleepless night, Tam decided it was time to create a solution to the constant need for keeping APIs well documented while also adding features quickly.

By the end of the year, Tam and his team had constructed what was to become Swagger 1.0. Swagger was not only a specification for writing APIs in a comprehensible fashion, it was also an array of tooling to help make that easier. Using Swagger, developers could automatically generate documentation and even clients for their APIs, and they could control access to those APIs with permissions.

“One guy on the team said, ‘Let’s render it using a nice HTML interface,’ and another guy on the team said, ‘let’s make it generate sample clients and SDKs,’ so we built that out. It was entirely a side project to get our stuff done. We released it to the public as a developer portal in 2010 and a lot of people reached out and said you should open source it,” said Tam.

That happened in 2011. Since that time, the project, specification and tooling have all grown in their own special ways. Swagger was originally named as an alternative to the Web Application Description Language: why WADL when you can Swagger. In 2015, Tam sold the specification, open source projects, and himself to SmartBear Software, where he is now the vice president of Swagger products.

Since then, however, the actual Swagger specification has moved on. It was donated to the Linux Foundation in late 2015 and has since been renamed the OpenAPI Project, under the OpenAPI Initiative.

“We had been approached by some very large companies that had started standardizing on Swagger at the time — Microsoft, IBM, Intuit, PayPal, Capital One — across different areas of the industry. Now, this is not a project run by Tony: now it’s run by SmartBear. We agreed to put the specification into a Linux Foundation project so it was free forever, to promote open usage of the specification so people could build tools and companies around it and not worry about what SmartBear was going to do with it,” said Tam.

Still, he added, SmartBear was his ideal choice as a shepherd for the Swagger open source projects, and he said they do not intend to directly monetize or split these tools up into product lines. Instead, said Tam, the goal is to help make everyone’s tools and software better through the spread of Swagger.

When Swagger 2.0 was released in 2014, the team saw 120,000 downloads per month, said Tam. By late 2015, that was up to 370,000 downloads per month. Today, Swagger is topping 100,000 downloads per day.

Today, a release candidate of version 3.0 of the Swagger specification is being prepared for final availability. The work on this version of the specification happened entirely within the OpenAPI Initiative, the first time such work has taken place there, as opposed to within Tam’s own working group.

Instead of leading that effort, Tam is focusing on the actual implementation of the specification in the Swagger tool line. This includes the core Swagger libraries in Java, Swagger UI, SwaggerHub, and the Swagger Editor. Smart Bear and Tam remain in charge of these projects and continue to develop these in an open source fashion.

For the 3.0 release, those tools were rewritten from the ground up, said Tam. They’ve now been completely rewritten and are having the 3.0 specifications added in. These tools and the specification itself should be ready at the end of May, though Tam said this was not a hard deadline.

Tam likens the split between Swagger the tooling and the OpenAPI 3.0 specification to the difference between HTML and web browsers. “When browsers were new, there wasn’t this notion of a specification underneath it,” said Tam.

For the 3.0 specification, Tam said there were a lot of major changes to the project. “One of the things we did early on was to use the JSON Schema as a way to represent payloads and to define the specification itself. JSON Schema is a validation structure. We did not support all of it. There are use cases you simply couldn’t do. If you have an API that returns fruit as a response, and also chairs, it wouldn’t work. We had a requirement that the response was deterministic, meaning you had to say in advance what you were going to return. We added something in the schema to allow you to return multiple types. That’s hard, but the community asked for it voraciously,” said Tam.

“One of the things people have been critical of within the Swagger specification is that we didn’t support hypermedia. While we don’t support hypermedia proper, we have added a feature called links, which are a design-time way to represent relationships between API calls. You don’t need to change your API to support OpenAPI links. It’s a description. You describe how your API supports them, and the tooling adds capabilities on top of that. That’s a big deal because, for a company like Atlassian, they have to support links in their API calls. Currently, they send this giant payload every time you make a request, with every possible link. This was a huge cost,” said Tam.

Finally, the OpenAPI 3.0 specification adds a: “Way to describe out-of-band or asynchronous requests. For WebHooks, or long running requests, or subscription-type mechanisms it’s essential to provide some way to describe not only how you handle exceptions or when a request might come back, with a response out-of-band, and more importantly, how you as a consumer need to handle it. You could go read how GitHub’s WebHooks work: read a giant document on how you implement a server to communicate, and it’s different from BitBucket’s, Google’s, and IBM’s. We made a mechanism that allows API designers or documentation experts to describe how out-of-band requests and responses work, and how you design your consumer to receive those calls,” said Tam.

As for the future of Swagger and the OpenAPI specification, Tam said there are two main philosophical drivers for the projects. “This is a description language, not a query language, nor a framework or design guideline. We’ve said you don’t need to use Tony’s server tools in order to implement it. You just need to be able to describe your API to be compliant. We can’t describe everything, or else it would look like WADL, but if you can describe your API you can have something that’s compliant with the specification. The good thing is once that happens, automated tooling can start generating clients and doing the work for you,” said Tam.

Capital One is a sponsor of InApps.

Feature image via Pixabay.