 Hello everyone, my name is Gabriel Caldwell, and this is add some swagger to your web apis with open api specification Thanks for joining me today My Twitter is at Gabriel Caldwell and the hashtag for the open source summit is Hashtag OSS or sorry OS summit If you want to send me a tweet or tweet something about the open source summit, please feel free to do so Here is the agenda for today So I'm gonna switch things around a little bit so first I was gonna tell you a little bit about me and then ask some questions about you But you know if I ask some questions about you first that might give some people a little bit of time to join so please you use the Q&A function and You know let me know kind of some of the reasons why you wanted to join this session in particular and what you're hoping to get out of the session and Kind of maybe about What you're interested in so I can try to tell of the session a little bit more towards majority of the people here because Everyone's interested in the same thing and I don't know I'm doing live coding which is It's More interesting for some less interesting further. So, you know, if you'd like to let me know kind of What you're interested in I can try and tailor it towards you and you know Skip some things that maybe are not applicable or focus in on some other things that are a little bit more applicable So again for those of you who just joins Please use the Q&A function. Just let me know Why you chose this session in particular and what you're hoping to get out of the session So, you know, I've seen a couple People already use this function one person said they like to document and in house API. So perfect. You're in the right section for that Yeah, if anyone else likes would like to use that Q&A function to let me know what you'd like to get out of the session we can Do that and I'll go back to the agenda now So we're going to get to know a little bit about me. I'd like to get to know a little bit about you And then we're going to talk about You know open API specification Dot net core and open source the difference the difference between documentation specification and definition And we'll take a look at the n-swipe tool chain Which again is specific to dot net but don't worry We're going to look at some alternative integrations For your favorite language your favorite framework. So if you're like i'm scala ride or die stick around This is not just dot net, you know, we're talking about concepts here. So it's not specific to dot net or c sharp Yeah So some people want to one person said they've used the open API and they want to see how they can Take advantage of that in their own API So someone likes swagger. I like swagger too. I'm a fan. Uh, so all right Let's get our swag off. So that's it for my slides. It's not a lot of slides. I uh, I don't like to Make slides usually when I present I do a lot of In-person presentations and I find that you know if I make slides So being a certain percentage of people that doesn't show up and they'll just download the slides And then you don't get the free beer or the free pizza or the swag whatever is being offered That time and then you know, we don't get to meet in person Uh, which is kind of an important fun thing. I can understand at least trying to type so I don't meet in person But you know, that's why I don't want to make slides So i'm just going to start sharing my screen as the back end for this And close my browser. Uh, so there's my newborn son, Elliot If something goes amiss during this presentation, let's just promise to Blame sleep deprivation and not my own ineptitude Okay, thanks So there's something up the edge browser. Uh, so on the topic of open source. Uh, it's now based on The chromium open source project So pretty soon we're going to see some improvements to memory management in chrome. Thanks to microsoft, which is something I never thought I ever would ever say But uh There we go And one of the things that I found really valuable since I don't make slides about edge is this collections function of Edge you can kind of create collections of websites Uh, and that works really well with my workflow because again, I don't make slides But I need something to keep me on track about what i'm supposed to talk about. So This is my collection for today Uh, and one of the neat things is that you can you know export all of the links In the collection to word or excel or you can copy all because it's important so it's all not that useful, but Copy all is great because I could just make a text document with it However, microsoft if you're listening this particular one doesn't work the other two work this one works But at the end of the session I will Copy all the links Into a text document and I will post them in the session abstract here So you can get all the links that I talk about in the session abstract After the session other cool part about this collections thing is that I could add a note Remember to Thanks to do that Um, all right, so It's a little bit about me I'm the cto of tsunami solutions And I know what you're thinking you're thinking Oh tsunami solutions that sounds like a really old timey company No one names their company xyz solutions anymore. It's all like Bitly and figly and safety shark and food llama and all sorts of crazy stuff. Um, yeah, it's true. We are an old timey company Been around since 1999 And uh, the idea behind the name was that you know, we thought that mobile data was going to be the next big wave And computing and it was going to be so big That it would be like a tsunami and I guess a lot, you know, we're right These are everywhere mobile data is uh, you pick with us um And in fact our product safety line was the first uh commercially available product to run on mobile data in the province of British Columbia, which is where we were based when we were first When we first started there was no mobile data in British Columbia But uh, it was in there and we use this other old timey thing Uh called wireless application protocol Which if you look at Wikipedia, uh, there's multiple issues because as with any type of ancient history a lot of things get lost along the way But let's start talking about, um, open api specification and apis in general Uh, and this is where I usually ask, uh, who's written an api, but I see from the q and a that, uh You know, some people have written apis before Uh, and I'm just gonna want to talk about about the challenges of apis and you know, a lot of people said that One of the biggest challenges, uh with with apis and writing the apis or even consuming apis Is documentation, uh, so I found this document, which is kind of an example of commercially available api out there So if you are here and you work for Garmin, I just chose you a random There's nothing particularly wrong about this document. It's actually quite a good document Um, but if you're a developer, you know, usually someone will hand you a document like this and we'll say, okay Here's uh the garmin api or here's api x And uh, we need to you know consume this api for our product. We need to integrate with this api So as a developer you kind of read through this You know and what what you're essentially doing is reading this documentation and trying to extract the specification from this document And and and think about all of the different, uh, possibilities That might you know are different error codes that might happen difference, you know eight here We have the htp status code. So You you know that okay, uh, this api is going to return success 200 success if the api is working or maybe if I didn't do something properly in my coding Uh, it's going to return for a woman authorized because you know, I didn't provide the proper Authentication token or what have you? Uh, so what is this list exhausted? That's kind of one of your questions. It's like you are these all of the status codes that the api might return Um, maybe your returns more. I don't know, you know, you kind of do this Uh, iterative process where you try different things against the api you try different possibilities You write all sorts of tests because you're curious about you know, what's going to happen when I consume this api is my integration going to work Uh, this is a common common problem and then again on Garmin side, you know, they have they have to you know, someone has to write the api And then they you know, either write the documentation themselves as a developer and we get bad documentation or I've made lots of bad documentation. It's not a knock against you. Um, or uh They they hand it to like a technical writer and then the technical writer has to read the developer's mind And then create the documentation. There's a lot of back and forth between the developer and the writer of the documentation And then someone will point out that oh, there was a little this was wrong or that was wrong and then we have this whole revision history um in the api So these are some of the common problems that people run into and You know, there must be a better way And of course there is this one. I'm going to show you today I'm going to use dot net core uh and c sharp and asp.net uh core To illustrate the concepts, but again, like I said, this is not something that's specific to Dot net or c sharp. So at the end we're going to review some of the the tools that are available for your favorite language or for your Favorite framework. So it's we're just talking really about concepts Um But you know, hopefully some of you like dot net core. Uh, it's open source, uh, which is again something We never thought Microsoft would do but look there's dot net core. It runs on linux I'm going to show you production api today that we have running on dot net core on linux so Hopefully that interests you a little bit us So open api specification is now here it is a linux foundation open source project And uh, I know this session was labeled open source project update, but I do not work On open api specification on the team. So I won't pretend to speak for them If you're interested on what's going on with the open api initiative, you can visit this website and again You know post all the links in the session abstract at the end of this session Uh, and if you're really interested like I am super fan, you might consider Visiting their github and if there's some improvement that you'd like to make Or some feature you'd like to see an open api specification You can yeah come here like these 36 other open pull requests and make a pull request on the open api specification Okay, uh, let's let's uh, let's jump into Visual studio now and take a look at An api so This is an api that I wrote Probably 10 years ago before there was dot net core Before there was this Before the open source movement really took hold in the world people for Microsoft saw the value of open source But I've kind of rewritten it For asp.net core to illustrate some of the possibilities of open api specification And also to illustrate some of the problems that you run into With an api I've stripped out all of the Authentication logic to kind of simplify it, but this is a real this is real production code. This is running in production right now um, and you know with your permission, I'd like to Maybe take a segue and talk about what this api does since we're not we're not using You know a to-do api or something like simple like return cats api that people usually use in demos we're using no real api so Let's let me stop much sharing here for a little bit and see if everyone's okay with taking a small segue into Learning about what this api does and why why we develop this api in the first place So If you don't mind using the q&a Just kind of letting me know if you're okay with With um, you know taking a segue into learning a little bit more about what this particular api does and the problem That we were trying to solve with this api Sounds like we're good to go So I will do that And I will share my screen again, and I will definitely keep it short We have an hour together. So I think we have time to get through everything that we are going to do so I do have some slides because you know 10 years ago. I did make slides So This api What it does is it works with lsd, and you know, you might be wondering to yourself. What is lsd? Well, it's not drugs It's a legal subdivision. It's locating It's a way of locating a piece of land in a specific top artist. So Earlier I was talking about our product safety line Which is a is a product that's designed to monitor the safety of people who work alone owner in isolation and it uses gps and A lot of our customers were coming to us and saying yeah, we like latitude We like longitude, but can you give us lsd and we thought like what are you talking about? Why? Or would you want lsd? Everyone in the world uses latitude and longitude? Why would you want lsd? But you know people kept asking for it and asking for it and and I thought they were crazy Uh, but after a while, you know, they keep asking for it. Uh You say okay, maybe we should give it to them And I looked a little bit further into it. Uh, and I found out some interesting things At first I thought Well, you know, you need to change what you're doing. You don't want a ts You want gps coordinates you want a latitude longitude like everyone knows we're 27.17461 780447 is right? Um But you know it was a pervasive problem There's an urgent problem and the customer was willing to pay for it. So we thought okay. Let's let's figure out how this thing works And let's give it to them Uh, so let's revisit that gps coordinate. Does anyone know where? Uh, this coordinate is I guess then no one knows right because it's not really like latitude and longitude. It's good If you have the tools to plot that latitude and longitude on the map, but this is where it is, right? It's here Um, and this is these are all the steps that you have to go through to actually find out where latitude and longitude is Other than you can type it into google maps and find out where it is But if you're using a real map, this is what you would have to do um Turns out in alberta, they divided the province into a bunch of polygons And it works kind of like what you see here. It's divided into the section township range and meridian And What they've done is this amazing thing is that they've named all the roads after it so the roads are actually maps and it makes a lot of sense if you tell someone like the ATS coordinates or the lsd coordinates. They know kind of like what corner that's on if you give someone a latitude and longitude Who knows where that is, but if you give someone in alberta Uh, the ATS coordinates the alberta township system coordinates They know where it is because the the roads are named after it. So, uh, to give our customers uh, those ATS coordinates we needed to Build an api to do that. Um It's kind of interesting how you do that because you can't really just do math You have to buy a shape file from the other government and then create a Spatial sql database Put all those coordinates in there and then get all the polygons out. So this is an api to do that So here's our controller This is pretty standard if you're used to doing that Uh, we have our data access So it's a get get the ATS descriptor for the coordinate that we've been provided from the query string. So if we run this api Let's take a second to build That's one of my favorite presenters says chug a chug a chug a And here we have the api And it's loading And then we see a blank screen. Uh, this is typical of a you know, uh, a developer that's trying to take advantage Of an api they try the api endpoint and they go, huh Doesn't work. I don't know what what this is It's supposed to work like this by the speed equals to one And then here we go. We get the lsd descriptor the ats descriptor Back from the api but as a developer, how are you supposed to know that? It's not very descriptive of the api endpoint if we go to Um, the root or the base of the url There's nothing there's no information to be found there. So Uh, you know, dot net lets us Do this a little bit better And back in the old timey days, uh If you were not building a web api you would build like a library And that's how you create the documentation So you go here Put a build and then you would make sure you checked off this xml documentation file And you'd have your your api document documented you ship from the library And your documentation is done But now in the world of web apis, you know, no one sees that xml documentation file Uh, but you know asp.net core Allows us to do things a little bit better if we go to the model that the query string is trying to bind to We can use this decorator So it's bind required on the latitude and longitude And now if you run the api again And we didn't provide anything in the query string again We get a little bit more informative answer back here that it's 400 We didn't provide the latitude and longitude, but Are there other properties that we're supposed to be providing in the query string? Don't know. There's no documentation. This error message is not that informative So you can also do these things Where you add an open api analyzer and how you do that Is you edit the project file And you tell it here add these open api analyzers And then if you try and build it compiler will tell you something they'll say Okay, you're returning a status code here 503 if for example the database server is not available You're returning a 503, but you never told anybody you're going to return a 503 So You can add this decorator that says your api produces this particular response type. It's going to return an ok 200 it's going to return 503 service on available And that's based off What the controller does it's also Just by it's going to this is just if we want to go really in depth into ASP.net core it's also going to return It's going to return this bad request as well if you don't provide anything in the query string We saw it's also going to return this bad request. So let's make sure we put that bad request in there And our api is getting a little bit better, right? We're telling whoever's trying to consume this api. These are all the possible status codes that are going to return from the api But you know, we're still missing documentation. We're still missing that specification in in our api. So We can do a little bit better And this is we're going to talk about the n-swag tool chain Which is a way to add the open api specification to your ASP.net apis, but like I said um We're just talking about some concepts here and we're going to take a look at some of the other tools that are available For adding open api specification to your api So what you would do Is you go and manage your nuget packages Go and install This particular nuget package here that ASP.net that n-swag.asp.net core knows Install that package for the dependencies And this n-swag by the way is an open source project. You can find it here And if there's something that you'd like to see in this project at the end of the presentation Something that you think would be really valuable again. You can make a portal request You can file an issue. You can do all those types of things Because it is open source So we just need to wire up a couple more things here To make this api really cool It is go to our startup.cs And we go to where all the services are registered And we register this service that has to do with swagger And then we're also going to Provide swagger ui So swagger ui Is another open source project And it's actually made by the people who originally started api specification And now they've moved on to a company called smart bear Which makes a lot of tools for an open api specification. So Yeah, you can find them Here at swagger.io and you can see as this is their copy of open api specification, but You can see that they have a lot of api development tools Specifically relating to swagger and I would definitely encourage checking them out because they make a lot of really really cool tools For inspecting your apis and building your apis testing your apis So it's a really really useful resource Okay, so Now that if we fire this thing up we're going to Again get that 400 because we haven't provided anything In the query string, but if we go to the base zero We get this swagger ui so the swagger ui Has a couple things here. It has a link to the swagger.json file and what the swagger.json file is Is the specification for api. So we've used The n-swipe toolchain to inspect the code and automatically Generate the specification for your api So what it's doing here is it's telling us about the parameters that are expected It's expecting this latitude this longitude. It's expecting this is unknown We'll talk a little bit about that as well So this is basically the model that it's expecting to bind to in the query string And then here's all the the possible response code to have 200 400 503 So it's basically inspected the code that we've written and provided a specification for api The swagger ui also allows you to try out the api So we can try out the api here Uh, what I'd like to show you a little bit more about where all of this is coming from So it's saying that you know, you can provide the latitude you can provide the longitude And it's giving you some hints. So Where are all these hints coming from so let's close this All of these hints are coming from the Comments that you've made in your code So some of the documentation for your api is now coming directly from your code and that's why And to get that that functionality you definitely have to go to to the build panel here and Check off this xml documentation file because what nsweg Is doing is it is inspecting that xml documentation file and pulling out all of your comments And then then it's providing one to the swagger ui But there was another thing in there that we were we were looking at is that that is unknown property and that's because The model that we're using for the api has a latitude and longitude, but it also has this is unknown property Which is a calculated property. So Maybe you don't want to expose that and there's a way to Stop that from being exposed in your specification and in the swagger ui You can just add this decorator Open api ignore And then now this is not exposed in your specification file or in your in your swagger ui Go back and take a look at that swagger ui goes to the to the to the We can now try out our api. So Let's try it a button Just try 51 Try to suggest it minus 112 Execute Now we see we got a response 200 back This is the ats descriptor for that particular latitude and longitude And it's pulling out all of the the the xml comments that you have Provided in your code to do this You see we have a little bit of a description of the api as well here. So if you wanted to You could expand on this and you could divide some more comprehensive documentation your swagger ui here To really just kind of make it a one-step process in terms of like coding your api creating the documentation and providing the specification to Anybody that wants to consume your api And if we go back to my notes here, they're supposed to keep me on track There's some other interesting things that you can Add to your auto-generated document. So besides what's there Add some terms of service to your to your api. You can add some contact info. You can even add a license to your api Can take a look at what that looks like here But hopefully in your mind, you're saying, uh, Gabriel, this like seems really simple. Why are we, uh, attending a Session about this? Well, it is really simple if you know what to do, right? Uh, and this is really really powerful. Um, it's super powerful It takes a lot of the pain points out of developing an api documenting an api or if you're developer consuming the api I hope that you find some value in it I also Showed in the session abstract that we are going to have some fun time permitting So I think we have lots of time left in the sessions. We're going to we're going to do some more fun things But I would like to kind of stop sharing my screen for a little bit and jump into the q and a so hopefully you have some questions about What I've just shown you and maybe we can go into a little bit more detail on some of the things that I've shown you Uh, or I can just answer your question. So please use the q and a such Sorry, use the q and a function to to ask some questions if you have some questions If not, I think don't worry. Don't have to have questions. Maybe I did my job And uh, we can just jump into some more fun things that kind of show you the power of building Open api specification into your api So just give people Another 30 seconds or so to to put the comments in there questions in there like I said, uh, we We'll also take a look at some of the the tools that are available for your favorite language and for your favorite framework So, uh, let's take a look at those And again, uh, all the links will be in the session abstract at the end of the session because I will definitely remember to do that and put them in there So get back here and here on okay, so Also, this is from so it's not there That's not the correct label But uh at this URL you can see some of the other tools that are available To For your favorite language your favorite framework Please feel free to go through that list as you can see it's quite exhaustive whatever Whatever you're into whether you're into java javascript lua typescript dot net node j s There's tons and tons of tools out there for you to Out open api specification or take advantage of an api that has open api specification So let me just jump back to the q&a here for a sec see if we have any questions now. Okay, great Uh Show you some of the more powerful things that you can do once you've added open api specification to you So this is a another tool by the same person that developed The nsoag tool chain we go suitor and again, this is the github This is called nsoag studio So this is a way that you can automatically generate a client Which is you know something that is Again, like we saw at the beginning a common task someone will hand you a documentation for an api and say we need to consume this api Please write a client for that api And do you have all those pain points that we've talked about? Uh, but if i'm running this api here again Do the base URL and so loads up you get my api specification file get that swagger.json file after that and in nsoag studio here, I can just paste in Uh the URL for the specification file and I could say okay, maybe I want a c-sharp client Or maybe I want a typescript client. Let's just take a look at the c-sharp client here You can go using this tool Probably the only thing you really care about there's many many options on how you want to generate the client but uh, where you want to do is go all the way down to the bottom and specify the path For your api. So let's just put it on my desktop All good files. So if we hit generate output here, what happens is the nsoag tool chain Goes and takes a look at that swagger.json file understands the specification And automatically generates the c-sharp client here for us to expand this a little bit. We can see It's written in my entire client for me. My job is done. I can just go home And here's an interesting thing is that there is a rest api for jira, which is one of the biggest tools out there They also support open api specifications. So if we look at their Openest api specification document, it's much more comprehensive They've built a lot of a lot of the they've built a lot of the documentation into the specification as well What we could just copy this URL here We can do the same thing Add in there for the c-sharp client go back to settings. Let's just Rename this here to jira client And generate the output That probably takes quite a while because the jira client is Very very very very complicated and so is the api of course Try how long it'll take here But eventually what will happen is we will have A jira client automatically generated. So here it is. So we have this very very comprehensive client for the jira api This is weeks and weeks and weeks of work for developer done Instantly through the magic of open api specification So again, this is if you build swagger into your or open api specification into your api You're providing a lot of value for anyone that consumes that api and you're saving them a lot of time And i'll show you some of some more powerful things that you can do as well But i'll quickly jump back to the q&a to see if anybody has any questions about what i've talked about so far Let us jump back So, uh, one of the other things i won't show you today that i'll that you can also do with the n sorry tool chain is that you can It supports ms. Whoops unintentionally Let's do that Is that it supports ms build arguments. So what you can do is you can Um Is that you can Have a client project for your api and then have that client regenerated every time you make a change to the api And if you build that into your dev ops pipeline, you can have the client regenerated And published every single time that you make a change to your api which again saves so much time Uh, and it's very very powerful And in case anyone's wondering, uh The n swag tool chain and open api specification in general also supports api versioning, right? So if you have an api that's been around for a long time or you're made a new api But if you want to keep it around for a long time, then there's going to be new versions in the future. Don't worry Uh api open api specification supports versioning and you'll be able to try different versions of that api in the swagger ui tool that i was showing earlier so uh What shall we do here now? Maybe i'll show you some of the kind of the powerful things that you can do if you have any api that should support swagger So what i'm going to do is go into microsoft forms here And i'm going to just make it you know stay with me here I think once this guy going into microsoft forms doesn't make any sense But let's say uh, for example, i was uh like a wildlife service in alberta And i wanted to make a tool That would allow people to report you know kind of wildlife in alberta and And then send someone to go check out that wildlife spotting report. And so i can make this pork survey And i can add a new question Uh, let's see what latitude did you see the wildlife at? And what longitude did you see the wildlife at? So it's latitude I'm here. I'm not going to another tool Call called power automate And power automate is kind of similar to if this then you can create kind of Custom business processes based on something happening So if i was alberta wildlife services, uh, i would might want something to happen When someone makes a new wildlife report through that form that i've created So i can name this calls And then when someone makes a wildlife report those response details um this one this Once i have that then This is the amazing part is that we can go here And add in a swagger api call if we want to So what we could do is we could take that latitude and longitude from the wildlife report and we could convert it into ats coordinates and then provide it to someone that is Responding to that wildlife report. And this is all without writing any code. We can make that api call because We have that open api specification on our api So i'll show you how this works One thing i need to do is We need to start this ngrok tunnel so that i can expose the api that's running on my local machine to the internet And if you're not familiar with ngrok, it's it's an amazing tool This place i need to come back there It's an amazing tool And this is exactly what it does. It's a public URL for exposing your local web server and it works on macOS windows linux free bsd. So if you're not familiar with this tool, it's an amazing tool So what i have now is i have this URL this ngrok URL that's exposing My api that's running locally on my machine So run that Sure, it's running Go back to power out of me For my api specification Let's see. Ah, yes, we forgot to do something Course the bane of all the numbers Uh, so we just have to enable course Since we have uh since this is a public api We have no problem just letting Anyone Make a request so Just make sure that we enable course here Security people are probably going crazy. So, you know, this may not apply to your api Make sure that you don't just copy and paste the code And add cores to any or at least allow anybody to make a request via course To your api but now the api is running go back to power automate But that's why your file and now that we've seen that power automate is picking up All of the documentation of the specification for the api We can see here it is it's a description of this integration of returns in api api a sort of ats descriptor The latitude and longitude and what we can do here now is that we can provide The answers to the questions so Someone puts in the latitude and someone puts in the longitude to that wildlife report survey that we created now We can take that Uh, we can make an api request to it. Let's just save that so we don't lose it here simple saving and then we can dispatch someone to make an inspection at that uh those particular coordinates, so let's just I want to open my email because I'll probably see all the emails from my mom telling me my broccoli, so I've made this email baby wildlife services at geniel.com their new wildlife Port and there it is wild life at ETS the response body here from the call to um the api to get the ats descriptor And boom now we've created a business process where someone is able to through this form here report some wildlife and then We're able to dispatch someone via email with the ats coordinates of that wildlife Now We can see that in action But I won't use this survey because it's linked to that one that I had that power on a flow that I just created and It doesn't actually work when you're running On local host Microsoft doesn't like that That was good reason because it's probably not going to be sticking around too long unless you buy that pro n rock subscription uh, so you can go try this one this prog now report and Preview it and try it out. Uh, so let's say A wildlife service email account See there's nothing in there And then I'm going to respond To my wildlife report here Put in coordinates of where I saw some wildlife submit that And then now I'll put it a wildlife services It's going to get an email in the inbox saying Okay, there's a new wildlife report wildlife has been spotted At this particular latitude and longitude and there's the ats preferred so now Someone that needs to respond to this Uh, I can go out and I have the ats coordinates and as we saw in the original presentation That's baked right into the road. So I don't even need to open maps open group of maps I know exactly where that is and I can go so these are some of the really powerful things that you can do If you add open api specification to Your api and again These are some of the the the tools that are available out there to do that So it's not just for csharp or asp.net chords available for your favorite language your favorite framework And I yeah, I'm a big fan. I hope you're now a big fan as well and then you add it to to your apis And I'll stop sharing and jump back in for any Questions now for I can find some answers Looks like we have reached the end of the session. So thanks everyone for joining me. I really appreciate your time and please Tweet me if you have any other questions And uh, I hope to see you using open api specification in your api sim Thanks