 I don't care what your politics is, but I'm pretty sure you agree this guy has swagger, right? You're here to essentially be a little bit more like him. I happen to like this guy a lot But I think he has swagger and this is what this talk is about. Let's get moving So first thing is let me mention to you that it's an honor to have Tony be part of This presentation with me Tony is the VP at SmartBear for swagger He happened to have created invented swagger and still involved and and the best part is a lot of you know me and You might have even heard about this this talk and this work that Mohammed and I from IBM Research here started, but what's cool is Tony told me yesterday I'm gonna add a few more things and I was like, ah cool. We'll chat about it today And what he showed me just blown my mind so much so that we kind of like decided okay Instead of doing the demo that Mohammed and I had as part of the talk we're gonna use his demo So you're gonna see this I promise you if you were doubting swagger Listen to Tony. It's a lot of pressure. Yeah all right Okay, well, thank you very much for that really easy setup So who here uses swagger API? Yeah, some people not enough people. Let me start out with a couple of things I'm gonna first talk to about what swagger is. It's really just a mechanism for describing API's it's for explaining what the contract is between a consumer and a service, right? Seems like something pretty simple and we'll go through that more in detail. I think this guy can explain what cloud foundry is Sure, I'll try oh Meaning now you went now. I think I think I think we'll get to it Timeline let's get to it. Yeah, let's get to it because I think what we want to do is get to the point where We'll pass your demos. These guys know about cloud foundry will skip. Let's skip to it Okay, right so back to this. Okay, so back to what swagger is many people when they say what swagger they say Well, it's a pretty UI a UI is part of it It's it's a very interesting part of it's actually in my opinion not the most powerful part of what swagger is But at its core swagger is a contract for API's right? I'm not a strict contract a little looser. We'll talk about that in a minute if it is If an API is correctly described in swagger It should be enough to both produce the API or consume it, right? It's important It's not enough to model it or make it look pretty or make docs It's really enough to consume it and understand everything about it So if you say that you call something and you get back a horse object You should get back a horse object instead of a cow object, right? So we want things to be really clear so that consumers don't have to guess There is a very rich tool set Ecosystem out there. There's thousands of projects on GitHub Some of them are better than the ones I work on Maybe But there's lots of things to help you get things done because it is a contract and once you have a contract you can do amazing stuff and very importantly it is a The swagger specification was the foundation for something called the open API specification Which means we donated a smart bear the company behind swagger Donated the spec to the Linux foundation so that lots of people can jump on and and contribute to it in a neutral fashion And move it forward as a standard for describing web services. So that's really exciting I can go into that in much more detail later, but now that there's all this pressure for a demo Let me get towards that first, right? so If you want to be a consumer of APIs you have or a producer for that matter. You have a couple of choices What do you call? What is the API endpoint? What is the the parameters all that sort of thing you can read the docs? So you see on the right hand side service broker docs here version 2.8 Very nicely created but still created by a human and still have to be read by a human a machine can't understand those very Very easily, right? If you want to consume it you have to Have a nice SDK if you're lucky sometimes they've got dependencies. You don't like it's not the language You like whatever everyone complains about SDKs and sometimes I don't blame them the parameters the inputs That go in what is a payload that comes in all of that sort of thing and then as a provider meaning the producer of an API Making all this stuff and describing is hard making SDKs is even harder because you don't always have the ability to write 50 different languages of client SDKs Users are great to have but there they can be annoying Especially when you're not doing a good job because then they say well, you didn't do this or this is wrong So that's all hard And also in general boilerplate blows. I don't need to say much more about that. So Swire can help in a number of ways There's different techniques for producing API's you can write code first a lot of people are doing this thing called design first And once you design an API you can generate automatically with right the right tooling clients and servers and That your job then is really to work on business logic right and that's a lot more fun than writing plumbing So if you've ever written routing tools and integrated some new framework that has lots of bugs That's not fun like your boss is gonna be happy if the business logic works really well So swagger is trying to help solve that and iterating right making changes to your definitions Having to code follow it everything being up to date being able to iterate quickly. That's a really big deal and swagger helps with that Some of the tools the things that swagger can help with The interactive editor you see here. I'm gonna show more about this But it's a mechanism to do a design first API meaning I will use a syntax Validated against a schema in here and I can design and visualize that API as I want as I work on it Inside you can see some of the the the Constructs of us of a swagger definition or open API spec definition. I'm in here. There's a path called catalog There's a summary right. It's human understandable. This is not a hard syntax understand if you've ever tried to Create a whistled by hand right like this is a dream come true Here we're saying that the description for the operation. What kind of code it produces or format it produces and JSON Description of the responses it says it's an array. I don't need to check and see if it's an object in a ray It's telling me exactly what it is and then I can just really explain all of these different aspects of what the What the API wants right and there's a great ecosystem of tooling And I'm going to walk you through this here is a screenshot of a project that I work on called swagger hub and it helps give you the ability to Kind of centralize these definitions and then bring them into your application life cycle right so Why does this matter to? This project cloud problem Well, let's say that you are in the business of creating a new a new service, right? There's things that you need to do in order to produce a new service to consume and fit in the ecosystem that you're all working with And you need to do a couple of things implement the broker API so that something can connect and get a proxy or Information to connect to your service. You need to implement the service And then you need to make an SDK so that those your consumers can actually call it, right? So let's walk let's walk through how a swagger Working inside of swagger hub can help out with that This is amazing demo that he totally said yeah, so so I guess it in some ways to set up Usually I would go through explaining cloud foundry and things like this and I figured let's keep it most people here You should probably know about Cloud Foundry already But the important thing is that Mohammed and I we created a bunch of description for different part of sea And what you're gonna see is one of those description and what Tony was able to do with it And hopefully that will convince you that we should take all of sea and add swagger to it So you'll see all right, so Since I'm lousy at typing and talking at the same time I made a little screencast, but but I want to walk you through what this is So this is a product called swagger hub. You can go to it. It's it's a free tool for API life cycle management design build deploy and integrate and so what I'm going to focus on is the the process of taking well-written definitions and Turn them into a real service right so the first thing here is if I go in here, and I search for CF demos I Have three definitions that max actually built or max and his team built and these are explaining different aspects of Services right and we take this one the CF broker Here is a definition that is effectively the interface So he's gone and described how you need to connect to the broker interface. You need to implement this to To to to be compliant with the 2.5 API You need to implement every aspect of this of this API now you can go through again You can read docs by hand and you can make all these endpoints you can say okay. There's a slash catalogs path I need to add this there's query parameters. I have to do all these things But he's gone through and on the hard part which is describe it in this in this definition format And here you can see what it looks like I can look in the UI and kind of scroll through it And here's the service instance API right so these are all mandatory correct me from wrong They're mandatory operations that if you want to make a compliant service. They have to implement okay So because they're all described I can do something pretty neat I can go and do something called fork this API right and so when I fork it I'm gonna bring a copy of it. It's pretty much analogous to the from the source code point of view I'm going to clone essentially clone this definition and bring it into my own project right and by bringing it into my own Project I can now do something with it because so imagine this is a read-only one I'm going to now materialize or instantiate this API right so here. I bring it into my own project I give it a name a version I can choose whether it's public or private and then it's done okay So that's exciting right so now I have my own copy you can see the URL change It's under my username Fagai or Fagai. I actually don't know how you pronounce it But now at this point I have a copy of this so now remember I said that swagger has a Whole tool chain for generating code and the code can be generated and you can do different things or that I can Generate a server and then download it. I can generate a client and download it But that workflow is not that great In that every time I make a change I download it then with files what files do I merge and so in in swagger What we did is we made a mechanism to generate code and push it directly to a repository Okay, so I'm gonna show you what that looks like if I click this gear There's something called an integration And there's different integrations here. I can choose I'm gonna focus on github And so what's gonna happen is is as I create this integration I'm going to link my definition Directly with github and the code generator so notice there's different generation targets here So I can generate code in all these different formats But since I'm creating a Broker I need to generate a service or a server that's going to respond to rest requests So I'm going to Because I'm a creature habit I can't learn any new languages. I'm gonna generate a Jacksrs version of this service. Of course, I could do different for languages. I could do go. I could do a PHP if I wanted a Ruby, but here I'm gonna do a Jacksrs version and When it generates code, I get a couple of options, right? So the worst thing would be if I'm generating code I'm pushing it into a github repository and then I go and I implement something and then I Generated again, and I blow over all my business logic, right? So that's not the idea We want you to have control over the code that you actually implement So I can here say if a file doesn't exist go ahead and create it if it does exist Leave it alone, right? So that's what this is here. This is called a provided path There's other things I can do like have fully managed paths. So it just is like if I'm gonna rename a model I need to blow it away Put make a new one. Let's let the code generator just own that and then files that I want to ignore, right? So by creating this integration now Every time I hit save What'll happen is the back end will go generate the code It'll sync it with the github repository and then push it, right? And so the beauty now is that without any doing any coding now I now have This project see a broker and a generated server Right explains where it comes from links to the open source so you can tweak it and do whatever you want and It actually will completely run so now imagine all that plumbing that I normally have to do all this routing that sort of thing It's just been done for me. So that's probably really small. Oh, you can read it. Okay, so I clone this repo I can immediately build it and With any luck I can actually run the server. Okay, and you have a fully working server which we can Launch I can jump into a browser. I can view the swagger definition and Then I can even make a call to one of the endpoints in this case the catalog endpoint, right? And of course, this doesn't do me a lot of good because it just says magic, but now note here This is the implementation. I just clone this and just read it So this all got pushed to GitHub all I have to do now is implement these methods and in this case here There's a Catalog method I implement this the framework is taken care of all the plumbing so that you just work on the business logic and And implement it. So then at that point If I do every method, I have a fully working broker application, right? So no code or anything like that But kind of this whole control and then so the beauty of this mechanism is that The interface that you must implement right the framework and all the plumbing and the routing the parameters and all of the options get Get done for you and your job is this one thing which is implementing the interface Okay, so now I've got the broker. I can do the same thing with my service and then plug it into the pipeline and then I've got a Working application really quickly and you don't have to work inside of this particular language You can work inside of any of the supported languages Really easily, right? Cool, so what you saw is essentially somebody implementing a service worker without having Any knowledge pretty much about the details of service worker just by going to the specification And this is the power of swagger, right? Obviously Tony knows swagger very well, but you saw the steps that he did. It's not unlike anything you could do So what we were trying to do with CF swagger, which is the incubation project is just sort of like motivate people for Doing this kind of things. I mean if this is not enough motivation for you, then we have even more So one of the things that we tried to do in the project CF swagger is to look at how we could essentially Document most of Cloud Foundry at least all of the external APIs And then obviously as Tony was asking the question is you don't want to just describe it You want to have value you want to bring value to the different projects? So if we focus again on the service worker What we found out is in addition to the demo that Tony showed which is essentially now all of a sudden all of you can go and implement your own service worker very quickly in different languages as well Which is the great part and keep it in sync with every time the service worker is updated One of the obvious question that came about for us was as we operate since I work for in in more of it as well work For IBM when we run service workers on BlueMix One of the big issues we started having is compatibility of the service workers because As the specification got updated not all of them are using swagger because that didn't exist on at that time Most of the service workers have to manually go update their service workers to support the new API So one obvious thing that we could try to find out is can we know which service worker is supporting? Which version of the API and that's what we did so we started looking at essentially creating what we call the test compliant kit for service workers In in some ways it's similar to if you're familiar with Java and You know in the past when Java had GSRs and they provided also a test compatibility kit a TCK that you could run Against your implementation of the GSR. That's the same idea Except guess what we implemented that TCK without writing a lot of code We wrote a generator of the TCK so every time the specification gets updated similar to how You know what Tony showed you where he generates a server We also created a generator So part of the swagger ecosystem is to allow the creation of those tools so that you can take the swagger Specification that you have for your API and generate something useful such as a TCK such as The servers or such as client code. So we did that What we had to do As part of our Specification which is the same specification that Tony used is to add a little bit of extensions to it So for instance, we added this X version Extension to essentially specify that this particular operation in the specification got introduced at version 2.6 So obviously you have to start at one particular version So what Tony showed you is version 2.5 and if you go to the version 2.6 then the new specification for that has These small extensions and this is all about it So as part of Tony designing the swagger specification and now with the open API They kind of looked ahead and saw that there's gonna be cases where people want to add something extra to the Specification because you know, you can't really think of everything ahead So these X dash or ways for you to essentially add a new annotation to the specification So we did that and then you and another one is for instance dependencies because one of the One of the things that we want to do in the TCK is to run it and be able to specify that oh when you Tried this broker against this TCK It failed at these operations so that way we will know that the broker did not implement a version But also which operation failed but obviously because the operations can kind of depend on each other This is a way for us to say there are dependencies across operation. So that's another one that we added This is kind of like a high-level overview. There's actually a video of the demo Not sure we have a lot of time to cover the whole video But there is a github. I'll point you to it but the way to think of it is that we take the swagger specification like we have here and We use this thing called go swagger. There's different sort of clients for swagger in different languages We happen to have implemented all of this and go but you could have implemented it out of other ways and what we Essentially created is a way to generate a tck out of the swagger specification Plus a series of templates for what the tck looks like So what ends up happening when you run the generator is you get a new tck or test compatibility kit Which is essentially a series of ginkgo tests right so similar to how the rest of Cloud Foundry if you're familiar with say Diego or or Bosch agent or Bosch in it a lot of the components that are written in go We use on sees ginkgo and go mega framework to Generate test cases. So those test cases become the tck and then you can take that and then spin up your Service worker and run the test against that service worker There's very minimal specific configuration you have to do but you essentially do that and then at the end We tell you which version So this is the demo what I'll do is I We don't have time for the whole demo But I will open it up and then show you towards the end what's happening is that we We show you here like how all of this thing gets set up and towards the end Like I think maybe around here you can see that we run the test and at the end We you can see here where we specify that For instance right here that the number of tasks pass and The tck compliance is 2.6, but in 2.4 5 It's also 100% compliant if you go through the whole demo We show you how we take a service worker and modify it so that it is compatible with one version and then we Make it uncompatible or we start in you know not compatible with 2.6 because there is like a parameter It gets introduced into that six that is optional and then when you run the test It shows you that the test failed on this one and then you implement that run the test again, and it passes So this is all available on the github project So I'll let you we have a pointer to this video so that you can take a look at it But we did more so let me get to that so what we also I Guess this I need to get to yep So what we also did was to To look at well, what else existed like this right to do a test compatibility to kit well, so turns out that blue mix had a little bit of a Set of tests that they ran again service bookers But it Exactly has the problem that we've been discussing where if you have a description and you're generating things from the Description that you avoid the test was stuck in version 2.3 And why is because we basically IBM hired an Intern and a set of interns to implement the test and then they implemented at the time They did their internship and then it's stuck there So you can now hire more engineers to go do more of that work Or if we go with our approach every time you regenerate so that's that's the value of swagger, right? We're not saying we're gonna replace engineers, so it don't you know, that's not the message here But there are series of things, you know boilerplate code things like Test where you are looking at a specification and you're trying to implement that or the server side piece of it Or the client side piece of it We can fix that problem for you right we can make it a little bit easier So obviously one thing we wanted to do I come from research Mohammed is in research We did a survey to sort of figure out where people had their pain point And whether or not this would be a useful thing to them And what we found is most people thought it would be very interesting and most people from the results And you can find all of this online We're not doing anything like this They were essentially either Implementing their own tests like we were doing in Bluemix or some of them were not even doing that So you would bring on a service broker that you say in your platform I support version 2.6 and you have no idea if that service worker is gonna support that version or like when next version 2.7 How many of your service brokers are implementing the next version right? So so those are the issues that we found out so you can go through the survey and and you'll see that Overall most people thought that they would be they would have they found this work to be useful So what I would ask you and we'll stop for some question is you know go explore You know not only swagger, but also the CF swagger It's essentially if you do a search for CF swagger, you'll find it. It's github.com Cloud Foundry Incubator CF swagger and then let us know I mean come to the Slack You know you'll find a channel also called CF swagger and and let's discuss So let me thank you and see if you have any questions that we can try to help answer So thanks for your time Don't be shy. There's a microphone Even if you like you think it's useless dude, that's fine, too Nobody Another perfect demo max, I guess yeah, you did it man. Yeah. All right. Well, thank you very much. Thanks a lot You