With SmartBear Software recently announcing that they are assuming responsibility for the Swagger API open-source project, many companies involved in API development tools have wondered if there will be major changes. Questions are also coming from the open-source community and from professional API developers.
InfoQ interviewed Tony Tam, founder of the Swagger project, to clear up some of the questions in the community. We sat down in Palo Alto to discuss the SmartBear announcement and how the community and businesses can participate in building a vibrant Swagger community. At GlueCon 2014, InfoQ covered the announcement of the Swagger 2.0 working group. Tony was kind enough to provide us with an update to our last interview on the goals of Swagger 2.0 and the problems it was intended to solve.
InfoQ: Can you explain SmartBear's rationale behind the acquisition of Reverb's Swagger project?
Tony Tam: The main reason for this partnership is that Swagger is not Reverb's core focus. Swagger needs to get more attention and Reverb has enough positive things to do. Swagger has been growing very fast and this move was needed so that Swagger isn't constrained. We are at an inflection point where partnering with someone who could help accelerate was important.
I had a long relationship with Ole Lensmar (CTO of SmartBear) and Lorinda Brandon (Director of API Partner Development at SmartBear). SmartBear was one of the first API products that supported Swagger formally. They have been neutral in the space. I feel confident that they won't use Swagger only for self-interest and that their vision of openness for APIs will benefit everyone. It is a very important that Swagger is sponsored by a company that will not force developers into using their proprietary stack. Of course, they can and should commercialize aspects of Swagger but I expect other companies and individuals will also use Swagger in commercial tools.
InfoQ: You have previously talked about the importance of pragmatism and vendor-neutrality during Swagger development. How will this spirit be preserved moving forward?
Tony: That's part of why we chose SmartBear. They will keep the specification and tooling in an open governance process. They are in the process of inviting industry experts and companies into the discussion around what the right open-governance model is for Swagger.
InfoQ: How can the community be involved in Swagger governance and development in the most useful ways?
Tony: We hope to involve smaller companies and individuals. The goal is to talk to everyone that has a stake in Swagger, not only the largest companies. We showed that too with the Working Group, which had about 500 people involved and where individuals had as much impact as big companies.
InfoQ: Will SmartBear continue to develop and support the open-source Swagger tooling as a top priority?
Tony: Yes. In fact, we released Milestone 2 of Swagger UI, Swagger JS, and Swagger Java in the last two days. The API industry is critical for this progress. Apigee has generously put two full-time developers on the OSS projects for the benefit of the community.
InfoQ: Will the community and its online resources be moved under SmartBear or will they remain independent?
Tony: It is still in the planning stage. My expectation is that most of the documents that we had created will stay in GitHub. There might be some non-reference-type guides moved under their website, but only if it makes sense.
InfoQ: You've been personally involved in many important ways in the Swagger project, including writing source code. How involved will you stay now?
Tony: You can look at the commit logs. There is no plan to change my involvement. There will be more people contributing but I won't move away from the project.
InfoQ: Specifications for version 2.0 of Swagger were announced last September. Can you summarize for us the main changes it brings compared to version 1.2?
Tony: More complete JSON Schema support, which allows our tooling to support strong typed clients. It's been simplified so it is easier to read. We now have formal constructs for references to promote reuse, and we've kept it bi-directional compatible with YAML.
InfoQ: The first milestone of the Swagger 2.0 tooling was released in February 2015. When do you plan to release the final version and what are the main changes?
Tony: There are five key projects that we should talk about. The milestones allow us to gather feedback. The final version will be released when it is ready, not any bit sooner. I would guess that will be in about six to eight weeks, but as software is never done, so I try to avoid the word "final".
InfoQ: Can you describe the various projects that are part of the Swagger framework and how they relate to, and are impacted by, the new 2.0 specification?
Tony: I'll talk about the ones written by us but there are more. The first project is Swagger JS. It is an interactive, dynamically created client for JavaScript that includes interactive help for both browser and server environments. It’s transparent to all versions of Swagger and one client can connect to any Swagger server implementation without recompilation. It does the majority of the work that you can see in Swagger UI. The way it's impacted by 2.0 is that we had to make its software API compatible regardless of the version of Swagger that it uses. The next project is Swagger UI, which builds an interface for any version of Swagger through interactive docs, based on metadata from Swagger JS. It has new organization mechanisms to be less URI-centric, based on user-defined tags.
The third project is the Swagger Core (for Java), which includes POJOs, JSON, and YAML serializers and integration with JAX-RS APIs. To support 2.0, we have rewritten it entirely in Java and retained almost the exact same software API, so upgrades from older versions are simply a dependency change. Writing it in pure Java helped us to shrink the size and make it easier for developers to contribute. Scala support has been moved into a separate project so it can evolve independently and with tooling that that language is accustomed to.
The fourth project is Swagger Codegen, which has been rewritten in Java for the same reasons as Swagger Core. It now leverages a standalone parser project that was written in part by the JSON Schema author to support universal reading of Swagger specs. In that project, there is now a standalone command-line tool as well as an online web app for code generation.
The last project is the Swagger Editor, which is an online or standalone design tool for Swagger that includes interactive documentation, real-time validation, and visualization. It's a brand new component.
There are other projects like Swagger for NodeJS. We are in the process of integrating a middleware component written by the Apigee open-source team. In a change from previous version, the Swagger spec is the DSL for the server.
There are about 40 known community-contributed projects for integrating with Swagger, not including the recently announced support built into the MS Visual Studio and Azure services.
InfoQ: Why did you decide to provide a Java tool chain for Swagger Codegen in addition to the initial one based on Scala?
Tony: The Java tool uses a JMustache engine that was 10 times faster and there are simply fewer people familiar with Scala, making it hard to contribute to the projects
InfoQ: Which major features couldn't make it into version 2.0 and what is the plan to support them?
Tony: The specs we put out had everything we wanted to put into it. We were not driven by a timeline. We felt it was the right next step for the specification. It's an evolution from the previous version and there will be more features eventually.
InfoQ: Is there an equivalent to RAML Traits in Swagger to describe crosscutting aspects of an API such as query parameters for pagination on collection resources?
Tony: We support JSON references and in YAML you can use anchors so there is nothing that is not shareable. It comes back to workflows as far as how references are resolved for readability and maintenance. We support a sensible referencing strategy.
InfoQ: Any plan yet for the next version of Swagger you can share with our readers?
Tony: It's something we will tackle with the governance group but changing specs too quickly is bad for adoption. From our view, it's not necessary either.
InfoQ: What are the main development workflows that you observed based on Swagger?
Tony: I've probably seen every possible development workflow, and it's obvious from interacting with both companies and individuals that there is no single "right answer". Swagger should not prescribe one way to write APIs. We provide tooling that is flexible and adaptable.
InfoQ: Do you see an evolution from API-code-first towards API-definition-first workflows?
Tony: I would say that while definition-first is not a new idea, it can be very effective in the right scenario. I believe there is no rational scenario where you could stop a developer fromwriting code before he has finished his API definition, or for that code to evolve outside of the specification.
InfoQ: Do you have any other thought to share with InfoQ readers about Swagger's future?
Tony: Swagger, like software, will always continue to evolve. We need input from the community and from real experiences to help this evolution. We are thrilled to see the support and commitment from the major API infrastructure players and software vendors but we're still early in the evolution of APIs and API tools. Swagger is opinionated and is not made to solve all problems, but that gives the community a foundation to build incredibly solid tools.
Disclaimer: the author of this article works for Restlet, a web API platform provider supporting several web API languages including Swagger and RAML.