SE Radio 726: Scott Kingsley on the Swagger Ecosystem

Speaker A: This is Software Engineering Radio, the podcast for professional developers on the web at se-radio.net se radio is brought to you by the IEEE Computer Society and by IEEE Software magazine online@computer.org software.

Speaker B: Welcome to software Engineering Radio. I'm your host today, Gregory Caphammer. Today's guest is Scott Kingsley. He's the VP of Engineering at SmartBear. Scott, welcome to Software Engineering Radio.

Speaker A: Thanks for having me, Greg.

Speaker B: 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?

Speaker A: Yeah, absolutely. So Swagger is 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 smartbird's built out, uh, 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.

Speaker B: 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 Open API specification. Is that right?

Speaker A: Yeah. So there's actually a really interesting beginning to Swagger and Open API. So there was this online dictionary company, Wordnik, 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 pretty cool. So they ended up releasing Swagger 1.0. This is the first major incarnation in 2011. And, and they continued to develop all the tools until they got to the Swagger 2.0 release in about 2014. 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 really good match. Smart bear has soapui. They know APIs really well. They know how to deal with open source and commercial projects. They found a good match. So Smart Bear took over Swagger. That was at the end of 2015. SmartBear donated Swagger 2.0, uh, to the Linux foundation and the Open API Initiative to take over the management and development of the specification itself, while SmartBear maintained the tooling, which was Swagger. Aha.

Speaker B: Uh-huh. So in my mind, I often think that Open API is the specification, and then Swagger and the Swagger ecosystem are like the tools for implementing the specification. Is that the right way for the listeners to think about it?

Speaker A: Yeah, that's exactly right. So the Open API 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 Devrel people involved with the community, understanding their needs. So we're highly involved in both aspects of it.

Speaker B: That's great. So one of the things that I know about open API 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?

Speaker A: Yeah, so in terms of language agnostics, so when you are building out defining your open API 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 specific from a language agnostic perspective. Your server side code, your client side code that's actually 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 TypeScript. 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, 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. And uh, this is mainly dealing with REST APIs which are served up over HTTP from that perspective.

Speaker B: 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?

Speaker A: Yeah, so if you go into the Swagger editor, for example, you have the option of defining that in JSON, you could define that in YAML. It really ultimately doesn't matter. You're defining against the same open API spec. So what I think you'll find is that humans, uh, 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 in Resolve JSON, for example, then to feed it into a computer system.

Speaker B: 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?

Speaker A: Exactly. So your server side implementation of your API is completely independent of the consumer of that API. So you could have, um, five different consumers in five different languages, all talking to a Typescript ah, based provider API.

Speaker B: 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?

Speaker A: Yeah, absolutely. So Swagger Editor, this is the tool where you have a text code editor window. That's your main focus when using this tool. So again, you could do this in 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're 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 really nice pretty documentation. It's got it laid out nicely. So all of your different paths and endpoints and schemas are laid out. It's got the 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 of like a consumer view of the API where editor is more of a provider view. And then lastly you mentioned Cogen. So CodeGen again is after you've built your spec and you want to feed that to, uh, API provider or an API consumer, it can help you develop server stubs or client SDKs in a whole slew of different languages.

Speaker B: Okay, so we're going to talk about CodeGen a little bit later in our episode. I wanted to pick up on 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?

Speaker A: 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 it's going to 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 can actually try it out against a mock server, or you could try it out against a live running API.

Speaker B: 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?

Speaker A: Yeah, exactly.

Speaker B: 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 ecosystem's adoption. Are there any insights you could share in that regard?

Speaker A: Yeah, so it's kind of hard on an open source project, especially like a 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 provides 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, like the commercial project. 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.

Speaker B: 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 in npm, it looks like there's multiple modules. There's Swagger ui, there's Swagger UI dist, and then there's Swagger UI react. Can you help us to understand how those are similar to and different from each other?

Speaker A: Yeah. So Swagger UI is a, uh, 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're embedding that in an application, you're gonna have to resolve all those dependencies and download them as part of your packaging and build process. If you want a fully independent distributable package, that's where Swagger UI disk comes into play. So that one's really just. There's one shot, you've got it, everything works, 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 React, as it kind of sounds, is our React component that people with React applications can embed pretty easily. And interestingly, from the numbers, Swagger UI Dist is way more popular than the other two. Swagger react and second, and SwaggerUI is actually the lowest by a decent amount.

Speaker B: 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?

Speaker A: Yeah. So fastapi, what they're doing is they're pulling in that, uh, swagger UIDist project. So 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 fast API users can set and control a little bit of flexibility on top of what comes out of the box from Swagger ui. Aha.

Speaker B: Uh-huh. So that's really helpful. Now, a moment ago, we mentioned the Try it out feature. And just quickly, if someone is shipping a fast API 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?

Speaker A: 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 it out is going to do. I mean, anyone could be doing lots of bad things to your system. If your security is 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 actually 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 it out. It's a really easy way to play with different parameters or get different responses.

Speaker B: 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?

Speaker A: 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 lots of controls and having an API 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.

Speaker B: 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 actually create the JSON or the YAML file. Is that correct?

Speaker A: 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 YAML or JSON, and then you're going to type that out. And as you're typing, it is aware of the open API 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 autocomplete and things like that based on the version that you're trying to implement at the time.

Speaker B: 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 actually integrate with their text editor or do they use it as a standalone product?

Speaker A: I don't know if anyone's embedding Swagger Editor like that. I mean, uh, interestingly enough. So Swagger Editor is built with the Monaco editor as a base, which is what VS code is also based on. So it's dealing with similar underlying technology there from a starting point.

Speaker B: 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?

Speaker A: 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 fed it into the generator. Next it's going to go to the parser which needs to dereference the API. So you've probably seen a lot of APIs have refs in them. So they're referencing another part of the spec or schema. Uh, 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 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. And then it's going to go to a templating engine. So handlebars or mustache. That templating engine is then m 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 Cogen, 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.

Speaker B: 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?

Speaker A: I think people are of very particular coding standards or styles or just the way they want their backend to be set up. And so if we as, uh, 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 they're going to have to do manual processing afterwards. And a lot of people run Swagger code gen 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 code gen, 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.

Speaker B: 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?

Speaker A: Yeah, absolutely. So Spectral is a, uh, linting governance standardization tool that you 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 OWASP 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 uh, 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. 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 it's heavily built into Swagger Studio in terms of like 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 have developed your spec first. You have your spec and say the backend team hasn't built the API yet, but you're 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, ah, 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 that existed.

Speaker B: 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?

Speaker A: Exactly.

Speaker B: 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 actually how an AI coding agent could consume m 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?

Speaker A: So throughout my career I've worked with a whole bunch of teams, a bunch of different companies, different projects with different number 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 kind of feel like a daunting task to take on, and it could take a while to get done. And I could see why teams might not want to do that. 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 really fast and easy to build that API up front. 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 than 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. They all agreed on the contract and the spec. The consuming team built out their service. They actually 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 have 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? 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 on them. Um, when you do 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, uh, I don't even know that you're really losing any time by following that practice.

Speaker B: 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 bidirectional contract testing. Can you help our listeners to understand what that process actually looks like?

Speaker A: Yeah. So people may be familiar with Pact Flow. So now swagger contract testing is the name of the product, but bidirectional contract testing is an, um, amazing feature that the team has built. Where historically, API functional testing is your QA's, your testing team looking at your own API that your team built, testing out the functionality, happy path, sad 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 bidirectional 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 to version the API.

Speaker B: Aha. Uh-huh. 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 CI CD 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 CI CD pipeline?

Speaker A: Yeah, absolutely. So say you got your spec first, so one of the things you can do is run the, uh, 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 is 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. 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. It's a valid spec. You can use tools like the Swagger Studio CLI or the Registry API. And so you can publish that specific. 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 kind of that 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.

Speaker B: Okay, that gives me a good sense on how I can use Swagger tools in a CI CD pipeline. I remember a while ago you talked about Pact or Packed Flow. Can you tell us a little bit more about what that tool is?

Speaker A: I think kind of covered in two different ways. So bidirectional contract testing and provider drift. So the two main functions of Pact Flow and those are built on the open source project Pact, which is available. So that's another open core model where Pact is available and then uh, that's embedded within Pact Flow as the commercial product. You know, it's been renamed Swagger Contract Testing.

Speaker B: 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 Pact Flow. And those tools actually provide what we call bidirectional contract testing. Is that the right way to say it? Yep.

Speaker A: Bidirectional contract testing and provider drift would be in the SWAGGER contract test product and then PACT supports consumer driven contract testing.

Speaker B: 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 actually 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?

Speaker A: Yeah, absolutely. So we've invested pretty heavily in AI over the past year because, I mean, obviously that's the way the world is going. But I mentioned earlier that someone may have spent hours, days, weeks typing out an uh, 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 uh, engineers 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, uh, 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, you know, maybe it's not a hundred 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 generate 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, add 500 responses everywhere, or you know, 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.

Speaker B: 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?

Speaker A: So we actually have a team, um, their job is to go through and check with the uh, latest models and which ones are working best and which ones work for your, each tool. So there's not necessarily like a blanket answer of uh, which model, which tool's working best. So we're looking at uh, anthropic models, Gemini models, OpenAI 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, uh, that's being developed now.

Speaker B: 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?

Speaker A: So in. 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 we're just dealing with that.

Speaker B: 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?

Speaker A: Yeah. Uh, so I think it was late 2024, anthropic came out with the concept of MCP servers. And this was a way to extend an LLM, um, and give it access to information that it wouldn't normally have. And so say, you know, 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 CLAUDE 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, claude code. You can now start using them, iterating, um, them, build code off of them. 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, because really was a game changer kind of for like, getting the latest and newest information available to LLMs. Um, so what we've done in Swagger is So all of SmartBear, we built a SmartBear MCP server. So we've released that and that's available for everyone. So if you are a consumer of our products, you can run that MCP server, put in your API key, and whether it's bugsnack, qmitry, reflect Swagger, you know, 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 in 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? Click OK, and it's going to download the bundle for you for that MCP server.

Speaker B: What you said was really, really helpful. Now first, just as one quick check in, when we're saying MCP here, we're talking about the model context protocol. Did I get that part right?

Speaker A: Yes, exactly.

Speaker B: 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?

Speaker A: Yeah, exactly. And that's part of the why that MCP server is so valuable, like I think for us, for our customers, is 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 M server is giving their LLM direct access to that API they're storing in the, uh, in the Swagger Registry.

Speaker B: Okay, I got it. So the idea is, if I've created an API and I want to essentially transport that API easily into Claude 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?

Speaker A: Yep, exactly.

Speaker B: Okay, awesome. Now, this actually 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?

Speaker A: 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 really just the most important part and using a standard ispec. So open API. So LLMs have been trained on like thousands and millions of examples of open APIs. So you really do want to be using a well known standard to be fed in because then you know, whether it's a traditional computer or a human or an LLM, probably going to get pretty good results because it's something that they're used to and they've been trained on. So you know, I think that it could be a wash. And you know, I've seen people try and say that, oh, it doesn't matter as much because agents are pretty good at uh, uh, dealing with, you know, bad APIs. 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, or if you're playing around and you 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, examples of it that it's really good at guessing what it's supposed to do. The problem lies in when you actually have a uh, 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 into production. And so you know, I would like that API spec to be well defined, good examples, be deterministic. I'm not going to skimp on it because you know, the more and more that we move towards agents writing code and you know, you're using expect 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 pretty quickly flowing through to production. So not something I'm going to risk with a sloppy specific.

Speaker B: So what are your thoughts about things like for example naming conventions in the API we talked before about how you can use a Lenter in order to enforce naming conventions when an AI agent is consuming the API. Do naming conventions matter in your experience?

Speaker A: 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, call it this, if that product, you know, else that, uh. 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 2 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.

Speaker B: Thanks, Scott. That was really helpful. So I know that we talked before about how if you've built an open API 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?

Speaker A: Yeah. So another place we've added, uh, a bunch of AI support is the developer portal that we built. So you've got your API in Swagger Studio, you've got that nice Swagger UI documentation on top of it. But, you know, the next layer is really how TOS workflows. A lot of companies want their own branded portal. So, you know, instead of going and seeing smartberry, you 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, you know, with the API that I fed, like write a how to, how to authenticate, write a, you know, overview section and 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 like, 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.

Speaker B: Okay, now in the next phase of our show, I wanted 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?

Speaker A: 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 you 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 codes properly defined. I think using schemas or shared models is good, so that you're not accidentally calling something different in one place than another. Having proper authentication, that's best practice for an API in general, but certainly you want that all included in there.

Speaker B: 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 open API 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?

Speaker A: 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 deprecate Support for Swagger 2.0. You're just going to have to support those Forever. And so when we came out with things like, uh, 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 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.

Speaker B: Wow, that's interesting. So, first of all, 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?

Speaker A: Yeah, so, I mean, there's kind uh, of two ways to deal with plugins in the open source. So I think most people probably are taking that open source component, pulling it locally and just building their own plugins and including them as well 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. You know, that's something you could go through the. There's a whole like, um, submission process, like how to work with the code base, how to contribute, and then you gotta 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. You know, they can use that on their own at that point.

Speaker B: Okay, so I myself have written a lot of fast APIs, and I've also interacted with multiple fast APIs. 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 fast API. 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 ecosystem? And then also is there any uh, kind of challenging or difficult example that you could share so that we can learn lessons from that as well?

Speaker A: Yeah, I mean in terms of our customers using our tools and success stories there, I know we've got, you know, 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 uh, 25% reduction in their test cycle just by having design first. 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 like all of their users had a better experience and just faster feedback cycles, less rework. They actually were using static PDFs as a documentation tool and so moving to an interactive and live documentation system and you know, 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.

Speaker B: Yeah, I can imagine that moving from a static PDF to a real Swagger UI was a big game changer for this organization.

Speaker A: 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 uh, Swagger V4 editor. There was a company, I, uh, 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 part of that is, you know, when the editor is taking your API, it has to go through and identify all the components and the sub components and it's trying to get to that point where it can lint it and autocomplete and validate it. And but really where I was getting stuck was all of 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 dereference that API again, many of which I just had to break off because it was an infinite loop with a circular reference that uh, it was just, the browser was just crashing when you got an API this big. And so that was part of the motivation between Swagger Editor v5, 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, open API, asyncapi, JSON schema, they're all mapping to API DOM behind the scenes. And so API DOM has its own dereferencer. It's got a tree sitter mechanism which um, I think GitHub and other tools use to turn code into usable elements and serve autocomplete. But by using API dom, which went through that whole tree, looked through the references, pre figured 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, uh, V5 editor.

Speaker B: 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.

Speaker A: The interesting thing was for a quote unquote normal size API, it handled it fine. This was just like a, uh, I don't remember, like almost 300,000 line API I think. Wow.

Speaker B: 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?

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

Speaker B: Now for our listeners who want to learn more about Swagger or some of the key components like Swagger UI or Swagger code, Gentlemen, 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?

Speaker A: Yeah, I mean there's a couple things that you can do. So if you go to Swagger IO, there is plenty of documentation there and if you want to do, you know, really basic setup, you can go the editor set up there to play it. So we're, we're actually hosting a version of Swagger Editor that people can just use to play around with and, and get started and see what that's like, you know, Playros Swagger ui so you don't have to go through NPM to download it, to set, uh, it up on your own system, just to, uh, you know, see what you want to do and kind of go there.

Speaker B: 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 right@swagger IO. 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?

Speaker A: I don't think so. I think we covered a lot today.

Speaker B: All right. 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.

Speaker A: Thank you, Greg.

Speaker B: All right, this is Gregory Kaphammer signing off for Software Engineering Radio. Thanks, everyone.

Speaker A: Thanks for listening to SE Radio, an educational program brought to you by ieee, uh, Software Magazine. For more about the podcast, including other episodes, visit our website@sc-radio.net to provide feedback. You can comment on each episode on the website or reach us on LinkedIn, Facebook, Twitter or through our Slack channel at scradio.slack.com youm can also email us at teamc-radio.net this and all other episodes of SE Radio is licensed under Creative Commons License 2.5. Thanks for listening.

Speaker B: It.