Search
Search
SE Radio Guest Scott Kingsley
June 26, 2026

SE Radio 726: Scott Kingsley on the Swagger Ecosystem

Scott Kingsley, a VP of Engineering at SmartBear, speaks with host Gregory Kapfhammer about the Swagger ecosystem. They discuss the user interface, editor, and Swagger CodeGen and how these tools support the creation and documentation of OpenAPI-compatible APIs. Scott describes how Swagger fits into frameworks like FastAPI, as well as how Swagger APIs can be exposed through the Model Context Protocol (MCP). The discussion closes with best practices for designing and testing APIs and the role that APIs play in a landscape in which AI agents are building and interacting with APIs.

Brought to you by IEEE Computer Society and IEEE Software magazine.

banner ad that says turn your knowledge into recognition - Software Professional Certification

Show Notes

Related Episodes

Other References

Transcript

Transcript brought to you by IEEE Software magazine.
This transcript was automatically generated. To suggest improvements in the text, please contact [email protected] and include the episode number and URL.

Gregory Kapfhammer 00:00:18 Welcome to Software Engineering Radio. I’m your host today, Gregory Kapfhammer. Today’s guest is Scott Kingsley, he’s the VP of Engineering at SmartBear. Scott, welcome to Software Engineering Radio.

Scott Kingsley 00:00:30 Thanks for having me, Greg.

Gregory Kapfhammer 00:00:31 Hey, today we’re going to be talking about some systems that you and your team build, which are all part of what we call the Swagger Ecosystem. Swagger helps engineers to design and to document and to test APIs at scale. And we’re going to focus all on how we build and test APIs. So Scott, in order to get our listeners started, can you tell us a few details about the tools that are a part of the Swagger ecosystem?

Scott Kingsley 00:00:57 Yeah, absolutely. So, Swagger’s really the umbrella name for the whole product suite. So, there’s a broad set of tools in there and at the center of all of it is the open-source project. So, you mentioned Swagger Editor, UI and CodeGen. And then on top of that we’ve got the commercial products. So, Smarts built out a whole suite of tools around them enabling the full API lifecycle development. So, from the conception of an API all the way through testing all the way through pushing to production. And so, those products are Studio a developer portal, contract testing, functional testing, and an API exploration client. And so, those tools enable your whole Scrum team, devs, QAs, PMs, tech writers, maybe even agents to all collaborate together, build your APIs and ship them with quality.

Gregory Kapfhammer 00:01:41 Okay, that was really helpful. So, some of the tools we’re going to focus on today are like Swagger Editor, Swagger UI, Swagger CodeGen. And my understanding is that Swagger has a connection to something called the OpenAPI specification. Is that right?

Scott Kingsley 00:01:56 Yeah, So, there’s actually an interesting beginning to Swagger and OpenAPI. So, there was this online dictionary company word Nick, who had a very big and public API and they had all these different consumers of that API that could only access parts of it depending on what they paid for or had access to. And so, they had all these struggles trying to find proprietary and different ways of telling each consumer which part of the API you got to access. So, to solve their own problem, they started developing this internal tooling to define a standard way of defining APIs, documenting APIs, documenting the same API in different ways. And after a while I think they realized, hey, we’re like really onto something. This is cool. So, they ended up releasing Swagger 1.0, this is the first major incarnation in 2011 and they continued to develop all the tools until they got to the Swagger 2.0 release in about 2014.

Scott Kingsley 00:02:51 So, then when we got to 2015, they were looking for a new steward of Swagger and they were looking around and found SmartBear as a company that they felt, hey, this looks like a good match. SmartBear has SOAP UI, they know APIs well, they know how to deal with open-source and commercial projects and find a good match. So, SmartBear took over Swagger. That was at the end of 2015. SmartBear donated Swagger 2.0 to the Linux Foundation and the OpenAPI initiative to take over the management and development of the specification itself while SmartBear maintained the tooling which was Swagger.

Gregory Kapfhammer 00:03:27 Aha. So, in my mind, I often think that OpenAPI is the specification and then Swagger and the Swagger ecosystem are like tools for implementing the specification. Is that the right way for the listeners to think about it?

Scott Kingsley 00:03:42 Yeah, that’s exactly right. So, the OpenAPI initiative is a highly collaborative effort with experts across all industries, really anyone interested in the advancement of APIs and API functionality. So, when they’re developing a new version of the spec, so, 3.0 to 3.1 to 3.2, that’s an independent group of people defining what that schema and spec should be. Now for SmartBear, we’re responsible for building tooling, both open-source and commercial on top of that. And so, for us, we have to stay on top of that because if we don’t, people are just going to build their own or find other tools to build. And when it comes to open-source versus commercial, if we don’t build it in open-source first, our commercial products aren’t going to work either. So, we’re pretty invested in staying on top of it. We even have a dedicated team of engineers that are always working on the open-source projects. We have devel people involved with a community understanding their needs. So, we’re highly involved in both aspects of it.

Gregory Kapfhammer 00:04:35 That’s great. So, one of the things that I know about OpenAPI specifications is that they’re described as being first of all language agnostic and second of all, the focus is on building an HTTP API. So, can you develop those two terms a little bit more? What’s the meaning of language agnostic and then what does it mean if it’s an HTTP API?

Scott Kingsley 00:04:56 Yeah, so in terms of language agnostic, when you are building out defining your OpenAPI spec, you can define that in JSON or YAML. That’s not what language agnostic means. Those are just two different ways you can define your spec from a language agnostic perspective, your server-side code, your client-side code, that’s serving up that API that’s consuming that API could really be in like any language that you want. So, a lot of teams are building their server-side implementations in Java or Python node type script. It doesn’t really matter as long as you’re building it to the spec. And so, one of the nice things is say you have a legacy service that serves up an API, you need to modernize it and rebuild it. You can rebuild it in a totally different language, but as long as you’re still building to that same API contract, then you know that you’re all set. And that’s one way that you can test that you haven’t broken any backwards compatibility. I mean this is mainly dealing with REST APIs which are served up over HGTP from that perspective.

Gregory Kapfhammer 00:05:51 Okay, that’s really helpful. Now you mentioned JSON and YAML. Can you give us a few concrete examples of some of the things that we would see inside of a JSON file that specifies an API?

Scott Kingsley 00:06:02 Yeah, so if you go into the Swagger Editor for example, you have the option of defining that JSON, you could define that in YAML. It ultimately doesn’t matter, you’re defining against the same OpenAPI spec. So, what I think you’ll find is that humans tend to prefer YAML. It’s a little bit more easily readable to the human eye, it’s easier to parse, it’s easier to get when it comes to computers or machines, they tend to prefer JSON. They can process that a little bit faster. So, as a human, you could pick either one you want, but I think a lot of times a person would define it in YAML and the Editor and then you may actually download it and resolve JSON, for example, then to feed it into a computer system.

Gregory Kapfhammer 00:06:43 Okay. So, then if I was aiming towards specifying my API, I might write that in YAML, then I have to actually prepare an implementation of that API, which I could perhaps implement in JavaScript. But if I’m understanding you correctly, I could still have a client of that API that was written in Python. Is that fair to say it that way?

Scott Kingsley 00:07:03 Exactly. So, your server-side implementation of your API is completely independent of the consumer of that API. So, you could have five different consumers in five different languages all talking to a TypeScript based provider, API.

Gregory Kapfhammer 00:07:17 Okay, that’s really helpful. Now I know that there’s three core open-source tools and we’re going to do a deep dive into them and learn more about how they work. But at the very start, can you tell us a little bit about Swagger Editor, Swagger UI and Swagger CodeGen three of the tools that I mentioned previously?

Scott Kingsley 00:07:34 Yeah, absolutely. So, Swagger Editor, this is the tool where you have a text slash code Editor window that’s your main focus when using this tool. So, again, you could do this at JSON, you could do it in YAML, but that’s what you’re actually typing out, developing editing your API. It’s got some features like code complete and hover over and jump to other locations of the file. But when you’re in your API design phase, this is the tool that you’re generally using to get that up and running. Now if you are a consumer of an API, So, say you wrote an API and I want to write code against it, you could send me the resulting API spec, I may open that in Swagger UI. So, Swagger UI has got that nice pretty documentation, it’s got it laid out nicely. So, all your different paths and endpoints and schemas are laid out. It’s got interactive documentation. So, if you click on an endpoint, it expands. You see all the path parameters; it’s got try it out built into it. So, that’s more like a consumer view of the API where Editor’s more of a provider view. And then lastly you mentioned CodeGen. So, CodeGen again is after you’ve built your spec and you want to feed that to an API provider or an API consumer, it can help you develop server stubs or client SDKs in a whole slew of different languages.

Gregory Kapfhammer 00:08:50 Okay. So, we’re going to talk about CodeGen a little bit later in our episode. I wanted to pick up one thing you said about Swagger UI. You mentioned that it has like a try it out option. Can you develop further what is this try it out option and if one of our listeners was using it, what would they see on their screen?

Scott Kingsley 00:09:08 Yeah, So, within each of the endpoints that you have, if you expand that endpoint, it’s got that button for try it out. And so, what that’s going to do is collect all of the different forms and parameters, collect them all together. You’re going to fill in any of the optional or required fields that are needed. So, say you have to enter in a couple strings for parameters passed in, then what you can do is you’ll click try it out and it’s actually going to go and form an HTTP request, execute that, and then in the window resulting it’ll show you the response code, the results, the response back from the server, which you could actually try it out against a mock server or you could try it out against a live running API.

Gregory Kapfhammer 00:09:47 Okay, So, Swagger UI gives us the ability to manually interact with the API directly in our browser. Is that the right way to think about it?

Scott Kingsley 00:09:56 Yeah, exactly.

Gregory Kapfhammer 00:09:57 Okay, cool. Now can you give us a little bit of a numerical insight in terms of what projects are adopting Swagger, the scale of the Swagger ecosystems adoption? Are there any insights you could share in that regard?

Scott Kingsley 00:10:11 Yeah, So, it’s kind of hard on an open-source project, especially like at GitHub code base to know how many people exactly are pulling it down. And we’re not like tracking that to that level of granularity, but one very easy way. So, the Swagger UI distribution packages are available on NPM-NPM provide pretty good stats. So, we can see there’s been 9 million downloads just last week of the three main Swagger UI distributions in terms of commercial projects. So, we have over 1.7 million APIs that we’re managing for our customers, whether private or public, on their end. And then they have on-prem installations. So, probably well over 2 million on the commercial product.

Gregory Kapfhammer 00:10:48 Okay. And we’re going to talk a little bit in a moment about the NPM modules. So, I’m delighted that you brought that up. For listeners who want to learn more about APIs, they’re welcome to go to Episode 387 of Software Engineering Radio or Episode 376 and we’ll link you to the show notes for both of those so you can learn more. So, since you mentioned NPM, let’s start talking about some of the specifics of the tools in the Swagger ecosystem and we’ll think a little bit more about Swagger UI. So, when I checked an NPM, it looked like there’s multiple modules, there’s Swagger UI, there’s Swagger UI disc, and then there’s Swagger UI React. Can you help us to understand how those are similar to and different from each other?

Scott Kingsley 00:11:29 Yeah. So, Swagger UI is a traditional NPM module. So, it’s intended for use to be embedded in a single page application. Now Swagger UI does not come with any of the dependent modules that you would need to run it. So, if you are embedding that in an application, you’re going to have to resolve all those dependencies and download them as part of your packaging and build process. If you want a fully independent distributor package, that’s where Swagger UI disc comes into play. So, that one’s just, there’s one shot, you’ve got it, everything works. So, it’s a bigger package, but you don’t need to do any work or manage any dependencies afterwards. And then the third module, Swagger UI Reacts as it kind of sounds, is a
react component that people with React applications can embed pretty easily. And interestingly from the numbers Swagger UI disc is way more popular than the other two. Swagger React and second Swagger UI is actually the lowest by a decent amount.

Gregory Kapfhammer 00:12:23 Okay, now I know many people who interact with Swagger UI might do so through a system like FastAPI. But FastAPI is for the Python ecosystem. So, can you help us to understand how do I use Swagger UI through a package like FastAPI, which is for Python?

Scott Kingsley 00:12:41 Yeah, so FastAPI, what they’re doing is they’re pulling in that Swagger UI disc project so that that fully bundled up project, they’re taking the latest of the V5 project pulling it in. And one thing they do that’s nice is you can encode set some of the parameters that can get passed into Swagger UI. So, there’s about 40 different parameters that control, look and feel and how things work and they’ve built that into their ecosystem so that FastAPI users can set and control a little bit of flexibility on top of what comes out of the box from Swagger UI.

Gregory Kapfhammer 00:13:14 Aha. So, that’s really helpful. Now, a moment ago we mentioned the Try It Out feature and just quickly, if someone is shipping a FastAPI and they’re actually going to ship it into production, do they turn off the Try It Out feature at that point? What are some of the best practices when it comes to using this feature of Swagger UI?

Scott Kingsley 00:13:32 I mean I would say generally for the most part it’s safe to leave on. I think when you think of something like security, this is calling your API through a browser. If you could do something through, try it out through your backend, you have much bigger problems with your API than what try Out’s going to do. I mean anyone could be doing lots of bad things to your system if your security’s not in place at the API layer. So, you’re going to have to put in your proper credentials assuming it has authentication set up on that API if it’s completely open, again, you have no security there. So, I think leaving it on is super helpful. Even at past companies I’ve worked at, we’ve left try it out on because for people that are writing code or developing or want to try out a certain scenario, just try out’s a really easy way to play with different parameters or get different responses.

Gregory Kapfhammer 00:14:19 Okay, that’s really helpful. So, let’s talk about security. You mentioned that a moment ago. Can you share with us some security best practices when it comes to actually exposing a live API endpoint? How does that work and what are some strategies that our listeners should follow?

Scott Kingsley 00:14:36 I think in terms of Swagger and Swagger projects, it’s really outside the scope of those, but really you want to have the right authentication set up. So, there’s various ways that you could control that. But certainly, working with your infrastructure, your DevOps teams, having the right network configuration and access, making sure if this is internal, there’s no outbound access that can get to it. You certainly would want to have things like rate limiting in place to make sure that you’re not going to get a DDoS attack or something like that. But with lots of controls and having an APEC gateway in front of it, there’s lots of nice security controls and rate limiting and throttling and error handling that they can put in front of your API as well.

Gregory Kapfhammer 00:15:11 Okay, thank you. Now I wanted to quickly double back to Swagger Editor and then I need to know all the details about what Code Swagger, CodeGen is generating. But when it comes to the Editor, that’s where it’s helping me to create the JSON or the YAML file, is that correct?

Scott Kingsley 00:15:28 Yeah. So, the Swagger Editor is at the very basic case. You’re starting with a blank editor window, then your choice whether you start with the YAML or JSON and then you’re going to type that out and as you’re typing it is aware of the OpenAPI version that you’re building at the moment. So, you’re defining that at the top of the file and so it knows what rules to evaluate, what functions should be there, and it can give you like highlighting and auto complete and things like that based on the version that you’re trying to implement at the time.

Gregory Kapfhammer 00:15:56 Okay. Now if one of our listeners happens to use VS Code or Neovim or other text Editors like Zed, is there a way for Swagger Editor to integrate with their text Editor or do they use it as a standalone product?

Scott Kingsley 00:16:11 I don’t know if anyone’s embedding Swagger Editor like that. I mean interestingly enough so Swagger Editor is built with the Monaco Editor as a base, which is what VS code is also based on. So, you’re dealing with similar underlying technology there from a starting point.

Gregory Kapfhammer 00:16:26 So, now let’s dive into Swagger CodeGen. Can you tell us some of the details about what specific code it’s actually generating and how it handles things like templating or other issues of that nature?

Scott Kingsley 00:16:38 Yeah, So, with Swagger CodeGen, you’ve got your API spec as the input file. So, that’s going to go into the generator. And what you’re going to tell the generator as part of the parameters is what is the language that you’re building for, what’s the output type that you’re looking for? So, is this a server stub, is this a client SDK, or it’ll even put documentation out as well. After you’ve fed it into the generator, next it’s going to go to the parser, which needs to deference the API. So, if you’ve probably seen a lot of APIs have refs in them, so they’re referencing another part of the spec or schema could even be something outside the specs, like a publicly available thing. In order to generate code, you have to take that reference and fill it in with the actual content. So, the parser is going to do that for you, flatten out the spec and then it’ll break it down into components and into a map, feed that into a language specific generator based on what you’ve passed in, in your parameters.

Scott Kingsley 00:17:32 And then it’s going to go to a templating engine. So, handlebars are mustache, that templating engine is then going to build the code in the format that you like. So, people have particular coding standards or code bases or you specifically, every time you run CodeGen, you want that same format. You want the code to come out the same, you want it like repeatable, you don’t want your downstream code to be impacted just because you regenerated the code. So, that template engine is what’s going to help you get it to your format in the same way every time. And then the output of that will be a bunch of build files, those get bundled together. Then you’ve got your server stub or your client SDK.

Gregory Kapfhammer 00:18:06 Okay, that’s really helpful. Now you mentioned things like how handlebars could be your templating engine to really land this point. Can you say a little bit more about why templating engines are so powerful at this stage of building an API?

Scott Kingsley 00:18:20 I think people are very particular coding standards or styles or just the way they want their backend to be set up. And so, if we as SmartBear just said, well this is how we generate code, well that’s just not going to work for a whole lot of people and companies. And if they’re going to have to do manual processing afterwards, a lot of people run Swagger CodeGen in every build. So, you’ve got a spec and even if the spec is the same or it was updated, they’re running it through CodeGen regenerating their server subs and their client SDKs if they had to go and manually make changes to how that code was formatted or how it was set up every time. And that really kind of takes away the usefulness of CodeGen to begin with. So, that’s where those templating engines come in super handy is that you can tailor it to what you need and how you want that output to be.

Gregory Kapfhammer 00:19:02 All right, that makes a lot of sense. Now when I was learning more about some of the open-source projects that Smartware helps to maintain, I remember reading about Spectral and then there was another tool called Prism. Can you tell us a little bit about those tools and then how they play into the overall creation or testing of a Swagger API?

Scott Kingsley 00:19:23 Yeah, absolutely. So, Spectral is a linting governance standardization tool that you’ll run against your API. So, there’s some rules you can get out of the box if you’re using Swagger Studio. So, this comes with a whole bunch of rules and standards, but you can add your own custom spectral rules. And basically, what you’re saying is these are the behaviors or the styles in my API that I want, there’s some nice public style guides available. So, there’s like an OASP top 10 public style guide that has a whole bunch of spectral rules built into it. So, you get a little security from your spec and then say you don’t want any verbs in endpoint names or you want things Kebab case or Camel case or there’s so, much that you can do with Spectral, which when you are an organization and you have an API program, you generally don’t want all of your teams just doing their own thing.

Scott Kingsley 00:20:11 You want to set a standard for the company, for the organization. So, Spectral comes in super handy, that is an open-source project, but project it’s heavily built into Swagger Studio in terms of how we’re doing standardization governance. So, yeah, that one’s directly embedded into Swagger Studio. So, Prism, that’s an API mocking library. So, you would’ve developed your spec first you have your spec and say the backend team hasn’t built the API yet, but your testers or your front end or someone wants to start playing around with the API, seeing how it’s going to behave. So, Prism’s a mocking tool, it’ll take the spec, it’ll serve something up that people can interact with. Now that’s not directly implemented in Swagger Studio, but that’s because we already have a fully-fledged mocking tool. It hasn’t made sense to replace it but something we already had existed.

Gregory Kapfhammer 00:20:55 Okay. So, in summary, Spectral is largely for API, Linting Prism is largely for API mocking and I can use those as a part of the overall Swagger ecosystem. Did I catch that correctly?

Scott Kingsley 00:21:08 Exactly.

Gregory Kapfhammer 00:21:09 Okay, good. Now one of the things that I wanted to dive into next was connected to like the various workflows and integration practices when it comes to using Swagger. And later in the episode we’re going to talk even further about how you could use AI to build an API or how an AI coding agent could consume an API. But before we get to that, my sense is that there’s a tension because as we’ve been talking, we’ve been talking about like making the spec or making the contract first. And I know that there are also ways where I can just simply dive in and implement the API directly and then I don’t have to worry about CodeGen or various tools of that nature. So, can you give our listeners a good lay of the land and talk about the trade-off between these approaches?

Scott Kingsley 00:21:58 So, throughout my career I’ve worked with a whole bunch of teams, a bunch of different companies, different projects with different numbers of consumers. And honestly, we’ve done it both ways. I’ve worked on Code First teams, I’ve worked on API design first teams. You could be successful with either one, but there are definitely pros and cons to either approach that you want to take. I guess what I would say is historically the biggest objection to API design first would be the amount of time that you feel that you’re spending defining that spec up front. And So, I’m thinking back like five, 10 years going into Swagger Editor as a blank slate and typing out a bunch of YAML, a bunch of JSON and learning about OpenAPI, different versions of the specs could try to not feel like a daunting task to take on and it, it could take a while to get done and I could see why teams might not want to do that.

Scott Kingsley 00:22:47 What I would say though is with the tooling available today and especially a lot of like we spent a lot of time in Studio, is taking away those barriers and just making it fast and easy to build that API upfront. And so, I mean I generally would highly advocate for design first and there’s a couple reasons for that. So, one is just unlocking parallel development. So, I love that analogy of building a bridge from both sides and you’ve got that contract in the middle and that contract is what’s going to ensure that they’re connecting in the right spot rather just hoping that they do. But even worse than that is only one side can start and the other side other teams just waiting and waiting and waiting until it’s done. So, I had a project late last year where one team was building an API, we did design first.

Scott Kingsley 00:23:30 They all agreed on the contract in the spec, the consuming team built out their service. They had it pushed out in production and live ready to go before the providing service was even done. They moved on to other things and then when the providing service was done, they pushed it to production and it seamlessly all went and everything was working. Otherwise, they would’ve been waiting that whole time for that first team to be done, to have the code written to then be able to build on top of it. And so, it really can be an accelerator in terms of teams if you’ve got distributed teams that are dependent on each other. The other big thing with Design first is that when you have organizational standards, I really think that it’s very healthy for an organization API program. Define those standards, define your governance rules, define your models and your domains, what should your data look like?

Scott Kingsley 00:24:18 Don’t let each team decide what to call a field. You can end up with like really a mess across your whole APIs if there isn’t some sort of governance or oversight into them. When you design first you can catch most of those things right away before the spec’s even done before a line of code is written. Really worst case is the code’s written deployed, you catch it later and if you have to version that API just to make a change and now support two versions, that’s a horrible experience for a team. So, catching those errors up front can save you a lot of time. And then when you look at something like CodeGen, if you write your spec up front, it can generate your server subs, your client SDKs. So, I don’t even know that you’re really losing any time by following that practice.

Gregory Kapfhammer 00:24:57 Thanks, that was really helpful. So, you mentioned the bridge a moment ago and you also talked about the idea of a contract and that made me think of something that’s called bi-directional contract testing. Can you help our listeners to understand what that process actually looks like?

Scott Kingsley 00:25:12 Yeah, So, people may be familiar with backflow. So, now Swagger contract testing is the name of the product, but bidirectional contract testing is an amazing feature that the team has built where historically API functional testing is your testing team looking at your own API that your team built, testing out the functionality happy path, side path, they’re trying to catch everything but there’s really no focus on how people are actually using your API like what are your consumers doing. So, bi-directional contract testing is built around the premise of the provider says what it does, all of your consumers say how they’re using it and then anytime you make a change you can see if that change is actually going to break that relationship between the provider and the consumer. And so, I’m sure many people have been in a situation where you would need to make a quick bug fix, it does affect the API, but you really don’t want to version the whole API just to make this change. Well bidirectional contract testing is going to catch like oh yeah, that’s a totally safe change to make because none of your consumers are using that field or here’s the two out of the five consumers that are using that field. You two can coordinate together and work on and manage like a coordinated release as opposed to just having no idea who uses it and therefore you have no choice but diversion the API.

Gregory Kapfhammer 00:26:29 Aha, I got it. So, oftentimes when we think about testing and we’ve already talked about linting and how there’s a tool that helps with linting, we think about running those types of things like in a CICD portfolio, maybe on GitHub actions or another system of that nature. If I’m building Swagger APIs, are there ways that I can run these testing techniques and linting techniques in some kind of CICD pipeline?

Scott Kingsley 00:26:53 Yeah, absolutely. So, say you got your spec first. So, one of the things you can do is run the Swagger CLI that’s going to make sure that your spec is just a valid spec. I mean that’s kind of like step zero is the spec actually valid? So, the contract test product has a feature that I absolutely love, which is called Provider Drift. So, what that’s going to do is in your build pipeline, it’s going to look at that spec, it’s going to look at your running code, it’s going to compare the two and say does your running code match your spec? And so, if those two don’t match, we have a problem. So, either your spec is out of date, which means your documentation’s going to be out of date or your code is wrong because they didn’t implement the spec correctly. And that needs to be addressed So, that those two things are in sync.

Scott Kingsley 00:27:37 And so, that’s just a build process pipeline check to say, hey do, are these two things in line or are they doing what they’re supposed to do? So, it really is a nice way to catch that and then say everything’s good. Your code matches your spec, that’s a valid spec. You can use tools like the Swagger Studio CLI or the Registry API and So, you can publish that spec. So, say you wanted to make it publicly available to your external consumers, or you could use that as a private repository for your internal customers to use as well. So, you have that kind of visibility of is it public, is it private? But still, that can be the central repo for where people are going to see documentation. And then the portal product is where if you’re building more like advanced documentation or workflows, you can update the spec there. So, now the latest copy of the spec is available.

Gregory Kapfhammer 00:28:23 Okay. That gives me a good sense of how I can use Swagger tools in a CICD pipeline. I remember a while ago you talked about Pact or PactFlow. Can you tell us a little bit more about what that tool is?

Scott Kingsley 00:28:35 I think kind of covered in two different ways, but it so, bi-directional contract testing and provider drift are the two main functions of PactFlow and those are built on the open-source project Pact which is available. So, that’s another like open core model where Pact is available and then that’s embedded within PactFlow as the commercial product it’s been renamed Swagger Contract Testing.

Gregory Kapfhammer 00:28:57 Okay, that was really helpful. So, the open-source tool is called Pact and then your commercial offering that goes along with that is called PactFlow. And those tools actually provide what we call bi-directional contract testing. Is that the right way to say it?

Scott Kingsley 00:29:11 Yep, bi-directional contract testing and provider drift would be in the Swagger contract test product and then Pact supports consumer driven contract testing.

Gregory Kapfhammer 00:29:21 Thanks for covering those details. That was really helpful. Now one of the things I know is that the Swagger ecosystem has mechanisms in place to help you to use AI in order to generate the API or to test components of the API. So, I’d like to start there first, can you tell us a little bit about how AI supports the process of designing the API all the way to documenting the API? What else should we learn about here?

Scott Kingsley 00:29:49 Yeah, absolutely. So, we’ve invested pretty heavily in AI over the past year because I mean obviously that’s, that’s the way the world is going, but I mentioned earlier that someone may have spent hours, days, weeks typing out an API spec in that code editor and that’s just not where anyone wants to be spending their time. So, one of the easiest things that we’ve done is create a natural language form for creating an API from scratch. And so, say an engineer working with their product manager to define the requirements, the API, what it should do, they can then take that, paste that into Swagger studio and then it’s going to go and generate your spec. But not only is it generating your spec, it’s going to do it following your standardization and governance rules that you’ve created and it’s going to conform to that out of the box. So, right away you’re going to get an API that comes back, that’s maybe it’s not a 100% perfect, but 85-90% of that work is all done for you and now you just kind of need to review it. And one of the nice things is it’s not just generated from scratch, but if you want to make updates you can use AI to do that as well. So, you could say for example, you missed 500 responses, added 500 responses everywhere or add a 401 here and that’ll just go do it for you. And so, the amount of time you’re spending writing JSON and YAML specific to OpenAPI 3.1 for example just gets smaller and smaller over time.

Gregory Kapfhammer 00:31:14 So, are there specific large language models or cloud providers that you recommend or that you commonly use when it comes to this approach for AI enabled API generation?

Scott Kingsley 00:31:25 So, we have a team, their job is to go through and check with the latest models and which ones are working best and which oneís work for each tool. So, there’s not necessarily a blanket answer of which model, which tool’s working best. So, we’re looking at anthropic models, Gemini models, open AI models and so, all of them just whichever one and sometimes the latest one is not necessarily the best. Sometimes it is, but we’re always trying to balance what’s the right one for this function that that’s being developed now.

Gregory Kapfhammer 00:31:56 Okay, So, if I’m actually using AI to generate my API or I think I can use API, I’m sorry AI and actually to generate the test cases, do I get to pick the model that I want to use as an LLM or is that something that the tool suite picks for me?

Scott Kingsley 00:32:13 Yeah. So, if you’re doing it through our tool, which again I would recommend because it’s going to use all your standardization governance rules, schemas templates, that type of thing. We’re picking the model so you don’t need to worry about it, but you also don’t need to worry about the cost associated with it because that we’re just dealing with that.

Gregory Kapfhammer 00:32:28 Okay, that’s helpful. Now one of the things in the context of AI is something that’s called an MCP server and in a way, I think this is connected to API creation and documentation. So, can you tell us a little bit, what is an MCP server and how does that connect to the AI and API landscape?

Scott Kingsley 00:32:46 Yeah, so I think it was late 2024 because Anthropic came out with the concept of MCP servers and this was a way to extend an LLM and give it access to information that it wouldn’t normally have. And so, say a model was trained in August of 2025 and that’s the latest set of information it has. But when you connect an MCP server to it, it now can access the tools and APIs that you’ve given it to in that MCP server. So, for us for example, we have an MCP server for Swagger. So, if you hook that up to Cloud code and say give me a list of all the APIs that I have, it literally can see up to the minute the list of APIs that you have access to, it can pull them down into say Cloud code. You can now start using them, iterating them build code off of them.

Scott Kingsley 00:33:36 And in early 2025 this became a standard that just every vendor started implementing. So, it wasn’t just Anthropic, it just, it took off like crazy and probably one of the fastest technologies I’ve seen just like blow up from like a buzzword to you must do this and everyone must implement it. It really was a game changer kind of for like getting the latest and newest information available to LLMs. What we’ve done in Swagger is, well so, oh SmartBear, we built a SmartBear MCP server. So, we’ve released that and that’s available for a bunch of URA. So, if you are a consumer of our products, you can run that MCP server, put in your API key and whether it’s bug not QMetry, Reflect, Swagger whatever, you can use that MCP server to get that latest information. But where it ties into APIs is if you’re building and managing APIs and Swagger Studio, literally at the click of a button you can click the button that says generate MCP server, it’s going to bring up a window with a list of the endpoints from that API you choose, which endpoints do I want to expose as MCP tools?

Scott Kingsley 00:34:43 Click Okay and it’s going to download the bundle for you for that MCP server.

Gregory Kapfhammer 00:34:48 What you said was really, really helpful. First, just as one quick check-in when we are saying MCP here, we’re talking about the Model Context Protocol. Did I get that part right?

Scott Kingsley 00:34:58 Yes, exactly.

Gregory Kapfhammer 00:34:59 Okay, So, we have the MCP server and it sounds like you’re saying that first of all MCP could be helpful for discovering existing APIs that are available and that additionally there’s a way in which if you have an API that was created with Swagger, you can use MCP or you can make an MCP server out of that API. Is that the right way to understand this?

Scott Kingsley 00:35:26 Yeah, exactly. And that’s part of the why that MCP server is so valuable. Like I think for us, for our customers if they’re storing their APIs in Swagger as their API registry, their customers can use our MCP server to pull them right into their LLM. So, if they want to generate consumer code build off of those, integrate with those APIs that MCP server is giving their LLM direct access to that API they’re storing in the, in the Swagger registry.

Gregory Kapfhammer 00:35:54 Okay, I got it. So, the idea is if I’ve created an API and I want to essentially transport that API easily into Cloud code or open code or other tools, I’m using an MCP server to make that API visible and usable for my coding agent. Is that the right way to think about it?

Scott Kingsley 00:36:14 Yep, exactly.

Gregory Kapfhammer 00:36:15 Okay, awesome. Now this leads me directly to our next topic. I’ve heard a lot of people talk about whether or not an API should be consumable for a human versus whether or not an API should be consumable by an MCP server or maybe even by a coding agent that’s not using MCP at all. So, can you weigh in here, tell us a little bit about the future of APIs.

Scott Kingsley 00:36:40 So, in the end, I think a spec is a spec I think whether it’s a human, whether it’s an agent whoever’s consuming it. The thing is using a spec is just the most important part. And using a standard spec, so OpenAPI, LLMs have been trained on like thousands and millions of examples of OpenAPI. So, you really do want to be using a well-known standard to be fed in because then whether itís just a traditional computer or a human or an LLM is probably going to get pretty good results because it’s something that they’re used to, and they’ve been trained on. So, I think that it could be a wash, and I’ve seen people try and say that, oh, it doesn’t matter as much because agents are pretty good at dealing with bad APIs.

Scott Kingsley 00:37:24 We’ve done some experimentation internally which has had some pretty interesting results where if you take, so like pet stores, like a famous example, API yes. Or if you’re playing around and you oh, do a transactions API like, just kind of like the typical play APIs that you would make, you can make really bad versions of those APIs and the LLM has seen so many examples of it, then it’s really good at guessing what it’s supposed to do. The problem lies when you have a complex API with your own domain knowledge and logic, that’s not something that an LLM seen a million times, you’re not going to get away with it. Having seen thousands of examples and being able to autocorrect and I certainly don’t trust an LLM guessing at code that’s going to go to production. And so, I would like that API spec to be well-defined, good examples, be deterministic. I’m not going to skimp on it because, the more that we move towards agents writing code and you’re using like spec driven development contracts driven development, there’s just less oversight into what’s going on. You really need well-structured design and specs and testing as that code’s like quickly flowing through to production. So, not something I’m going to risk with a sloppy spec.

Gregory Kapfhammer 00:38:37 So, what are your thoughts about things like, for example, naming conventions in the API? We talked before about how you can use a linter in order to enforce naming conventions. When an AI agent is consuming the API do naming conventions matter in your experience?

Scott Kingsley 00:38:54 You know, honestly, it’s tough to say. I think that we’re in a world today where you still have a lot of humans writing code. You still have a lot of humans reading and debugging code and the number of agents writing, reading and dealing with code is increasing significantly. But when I was at a previous company, we had different divisions and we each called the same thing something different in our model. And I remember one of our customers saying, hey, we’re trying to integrate across your three products. Our code is a mess because it’s if this product calls it this, if that product else that, and they had all this kind of crazy code dealing with the fact that the same thing was named different things in different places. Now can an agent write code to deal with that? Sure. Can another agent read code to deal with that? Sure. But like if say something goes wrong and I’m the engineer pulled into debug it and I go into this code base and it’s just a complete mess to trace through and I’m having a hard time following it, like I certainly don’t want to be that guy on call at two in the morning trying to trace through that code. So, I would certainly still suggest following best practices using consistent and good naming and standardizing across your API portfolio.

Gregory Kapfhammer 00:40:03 Thanks Scott, that was really helpful. So, I know that we talked before about how if you’ve built an OpenAPI spec and you’ve used Swagger to implement that spec, that then there’s a way to take that spec and that API and make it available through MCP. Are there any other ways in which there’s AI integrated into the tool chain associated with designing and specifying and then actually building and shipping APIs?

Scott Kingsley 00:40:31 Yeah, so another place we’ve added, a bunch of AI support is the developer portal that we built. So, you’ve got your API and Swagger studio, you’ve got that nice Swagger UI documentation on top of it, but the next layer is really how-tos workflows. A lot of companies want their own branded portal. So, instead of going and seeing smart brand, you’ve got your own look and feel color schemes, images. So, you can take your APIs that are stored in studio and build out your whole developer portal with your own domain, again, look and feel. And so you’ll import that API and one of the features we have for AI is, so all of that documentation code that you’re writing, you can use natural language to say, with the API that I fed, like write a how to authenticate, write an overview section that’s going to feed a lot of the documentation that you need just right out of the gate and save you from doing a whole lot of writing yourself. Similarly, if you don’t like the way it was worded or the tone you can ask it to update a certain section or things like that. Really trying to make that documentation or developer portal experience as nice as possible.

Gregory Kapfhammer 00:41:39 Okay. Now in the next phase of our show, I want to talk about quality and Standards and Governance. Many people talk about how they’ve built a high-quality API, what does it mean if we say that it’s a top notch or high-quality API? What are the ways to understand the word quality in the context of an API?

Scott Kingsley 00:41:59 I think that can come in multiple forms or formats. It could be an organizationally good API. So, like for your, like the way you as an organization want your APIs structured and built and to be similar, if you’ve got one team going off on their own, doing it differently, well for your organization, that’s not a very good API for just any API in general. So, certainly want to have examples built-in there. So, that’s going to help humans and agents consume that. API knowing what good looks like or how to use it, have your response code properly defined. I think using schemas or shared models is, is good So, that you’re not accidentally calling something different in one place than another, having proper authentication, that’s just best practice for an API in general, but certainly you want that all are included in there.

Gregory Kapfhammer 00:42:48 Okay. Now before we draw our episode to a conclusion, I wondered if you could take a minute to reflect on the fact that this project has been around for, if I remember correctly, almost 15 years. So, what are some of the ins and outs, what are some of the things that are the same when it comes to OpenAPI and Swagger? How have things changed over the years? And then can you tell us a little bit more about what the future of Swagger tooling looks like?

Scott Kingsley 00:43:15 Yeah, so I think one of the interesting things that we’ve seen over time is that people are still using very, very old versions of APIs and they just continue to use them. And so, it’s not the type of thing where we even have any choice to like deprecate support for, Swagger 2.0. Like you’re just going to have to support those forever. And so, when we came out with things like, Swagger Editor five, just like really newer versions, everything really became about componentizing and having a nice plugin architecture so that when we came out with support for 3.0, 3.1, 3.2, you’re really just adding on and into that plugin structure so that you can kind of leave what was there as functioning and working and just add in that that new structure because we know we can’t deprecate it, we know we can’t pull out support. So, a lot of like the design and development went into like knowing that it’s a lot of these are going to be around forever. I mean, we still get plenty of requests to add SOAP support to Swagger Studio at this point.

Gregory Kapfhammer 00:44:15 Wow, that’s interesting. So first, I hear you saying APIs are very long living and that you often can’t deprecate them. And I’m glad you mentioned the plugin approach because I wanted to talk about that a little bit further. Can you tell our listeners more about what it means to build a plugin and then how that plugin becomes a part of the official API?

Scott Kingsley 00:44:36 Yeah, So, I mean there’s kind of two ways to deal with plugins in the open-source. I think most people probably are taking that open-source component, pulling it locally and just building their own plugins and including them. It was also for like whatever custom functionality that they’re trying to build. And so, there’s pretty good documentation on the site about like how the plugins work, what the structure is, like where you would put it, like what you would overwrite, what you would add to. In terms of like adding a new plugin overall to the like full open-source public version. That’s something you could go through the, there’s a whole like, submission process, like how to work with the code base, how to contribute, and then you kind of submit your idea and then we’ll review that idea, see if it’s something that makes sense for everybody to be a part of and have, or if that’s like, that’s a great idea but it doesn’t belong in the core repository that they can use that on their own at that point.

Gregory Kapfhammer 00:45:27 Okay. So, I myself have written a lot of FastAPIs and I’ve also interacted with multiple FastAPIs and our listeners can check the show notes for an episode where we specifically focused on FastAPI. So, from my vantage point FastAPI is one of the success stories associated with Swagger because Swagger is bundled into every FastAPI I’m wondering, can you share with our listeners some other type of success story when it comes to the adoption of Swagger and the tools in the Swagger or ecosystem? And then also, is there any kind of challenging or difficult example that you could share So, that we can learn lessons from that as well?

Scott Kingsley 00:46:09 Yeah, I mean in terms of our customers using our tools and success stories there, I know we’ve got, there’s a customer NISC who did a case study with us recently where they adopted an API Design first mentality. They started using developer portal using the tools and they found that they got a 25% reduction in their test cycle just by having Design First all like that whole process of being on the same page up front, just like was just a big help for them, their better experience overall. So, all their users had better experience of just faster feedback cycles, less rework. They were using static PDFs as a documentation tool. And so, moving to an interactive and live documentation system and something that could change on the fly, like as your API is updated, was just like a much better experience but much simpler for them.

Gregory Kapfhammer 00:46:59 Yeah, I can imagine that moving from a static PDF to a real Swagger UI was a big game changer for this organization.

Scott Kingsley 00:47:08 Yeah. And then So, you asked about challenges. So, one of the things I would say was probably the biggest challenge, and this is when we had the, the Swagger V4 Editor, there was a company, I won’t say their name, who made a very, very, very large API that was just like massively expanded, like everything that they did. And this blew up the Editor. And, and part of that is, when the Editor is taking your API it must go through and identify all the components and the sub-components and just trying to get to that point where it can lint it and auto complete and validate it. And, but really where I was getting stuck was all the references. So, it had super deep references and in many times circular references. And so, the amount of memory it was consuming for the system to get through all of these cycles and d reference that API again, many of which had just had to break off because it was an infinite loop with a circular reference that it, it was just the browser was just crashing when you, we got an API this big.

Scott Kingsley 00:48:11 And so, that was part of the motivation between Swagger Editor V five, which we switched to a whole different underlying model. So, API DOM is the data structure we built, which actually whether you use JSON, YAML OpenAPI ASY, API, JSON schema, they’re all mapping to API DOM behind the scenes. And So, API Dom has its own de reference, it’s got a tree sitter mechanism, which, I think GitHub and other tools used to turn code and usable elements and serve auto complete. But by using API DOM, which went through that whole tree, looked through the references, prefigured out which ones were going to be circular. The whole process was a little bit slower, but it was much more performant, much more stable, really ended up being like the foundation of that V5 Editor.

Gregory Kapfhammer 00:48:58 Wow, that’s really interesting. So, you’re saying when you have circular references in the V4 version of the tool, you could actually get a situation where the system was in an infinite loop and then it would just crash.

Scott Kingsley 00:49:10 The interesting thing was for a quote unquote normal size API, it handled it fine. This was just like a, I don’t remember like almost 300,000 line a PII think.

Gregory Kapfhammer 00:49:21 Wow. And then finally, I heard you a moment ago mention tree sitter. Can you expand on that a little bit for our listeners So, they understand what a tree sitter parser is and how it might have worked in the V5 version of the system?

Scott Kingsley 00:49:33 Yeah, so the API DOM is breaking up that spec into that sort of unified data structure or data model. And tree sitter is helping to kind of annotate each of those components so that when the linting functions, the auto complete functions, they’re able to identify the specific type of component that they’re acting on. And that’s enabling that hover overs, the linting, the auto complete in a more efficient way than would kind of normally be done.

Gregory Kapfhammer 00:50:01 Now for our listeners who want to learn more about Swagger or some of the key components like Swagger UI or Swagger CodeGen, can you give them some advice on what they need to do in order to get started in order to learn more about it and then maybe actually to build their own API using Swagger?

Scott Kingsley 00:50:18 Yeah, I mean there’s a couple things that you can do. So, if you go to Swagger.io, there’s plenty of documentation there and if you want to do, really basic setup, you can go the Editors set up there to play it. So, we’re actually hosting a version of Swagger Editor that people can just use to play around with and get started and see what that’s like. You know, play around Swagger UI so you don’t have to go through NPM to download it, to set it up on your own system, just to see what you want to do and kind of go there.

Gregory Kapfhammer 00:50:47 Okay. Yeah, and I’ve tried that out and for me that was also, really helpful because I didn’t have to install anything. I didn’t have to set up a developer tool chain. I could just try it out [email protected]. Now, what I wanted to do quickly was check in with you. Are there any topics that we haven’t covered that you think we should cover so that listeners can get a fuller or more rich sense of Swagger and the ecosystem of Swagger tools?

Scott Kingsley 00:51:11 I don’t think so. I think we covered a lot today.

Gregory Kapfhammer 00:51:13 Alright. Hey, thanks for all of this time that you have devoted to teaching our listeners about Swagger UI, Swagger CodeGen, and the other parts that go in. I was excited to talk about how we can use AI to consume an API or even use AI in order to generate one. Thanks for your time. It was really a lot of fun to talk with you, Scott. I hope you enjoyed the episode. Thank you very much.

Scott Kingsley 00:51:36 Thank you, Greg.

Gregory Kapfhammer 00:51:37 All right, this is Gregory Kapfhammer signing off for Software Engineering Radio. Thanks everyone.

[End of Audio]

Tagged as:
Join the discussion

More from this show

Menu

Recent posts