Full transcript
0:00so I'm Kecia and I work on the product
0:02marketing side of swagger and swagger
0:04hub and today we'll just be diving into
0:07headfirst on like what really is the
0:08open API specification so we're gonna be
0:11starting off with understanding giving a
0:12quick overview of the open API
0:14specification like what is and
0:16specifically open a POS 3.0 we'll be
0:19talking more about what's new in OS
0:21Suite 3.0 and we did a webinar about
0:24last month which meant more into details
0:27and like what were the new features this
0:28is just gonna be a quick overview of the
0:30new field of just the highlights of the
0:32new features and then finally of course
0:34we are gonna be going in and doing a
0:36live demo on swagger hub like when
0:38you're actually we're gonna be taking an
0:41idea of what any case suppose me and
0:43then designing it from scratch using OS
0:453.0 and of course you'll always will
0:50always have time for Q&A there we go so
0:56so really let's look at listen if you
0:59have to think about why the open API
1:00specification egg says we need to start
1:02thinking more than API a first so an API
1:04is just a set of protocols that allows
1:06different applications or logical units
1:08to communicate right you know so think
1:10of it as a purifying channel of data
1:13exchange that gets exchanged between
1:15systems the receiving unit is usually a
1:18client which then puts out a request and
1:20then of course there's gonna be a
1:21response which comes in from the server
1:23when the client hits the server with the
1:26specific request know an API
1:29traditionally it's been is sort of like
1:31a black box at least before before an
1:34interface was defined using swagger or
1:36the opening pacification right it was
1:38just like a set of protocols that was
1:41also built by a way that actually goes
1:46through a life cycle of different
1:48personas so you have the architect to go
1:50about from a top-level overview
1:52understanding how the API supposed to
1:54behave and function you'll have the
1:55developers and the testers were making
1:57sure that the API works works correctly
2:00works as intended and they're also
2:02writing business logic against different
2:03resources and of course you have the
2:05technical writers who actually have to
2:07document this API to make sure that your
2:08end the end consumers of this API know
2:10what this API does now however in
2:14traditional sense when when people
2:17actually approach the API development
2:20without using a restful interface or
2:22like a design per se there are some
2:25major problems that they encounter the
2:26first one of course is that maintaining
2:28documentation tests and implementation
2:31was hard right because you know all
2:34because aps are just like any other
2:35product they do go to update they go
2:37they do go to an agile iteration of new
2:40features new updates new bug fixes and
2:42then you have all because we have such a
2:44diverse set of teams or working on these
2:47API so maintaining all of their
2:48different units together was incredibly
2:51hard implement and because there was no
2:54real defined design on how the API
2:56should look and feel and behave
2:58implementation was was sort of all over
3:01the place and always came at the cost of
3:02the end-users experience so you know
3:05because there was such a need to like
3:06push the API out really quickly and
3:08because there was no plan approach like
3:10actually building an API the end user
3:12the end consumer of the API software and
3:15finally of course communication between
3:16different services built and different
3:18program programming languages was not
3:20always easy right so for example if you
3:22have a service that's built in Ruby and
3:24I have a service that's built in nodejs
3:26we shouldn't be imposing restrictions on
3:28each other saying you know I can only
3:29consume your service if I say get a ruby
3:31SDK from you or like oh so you know that
3:33sdk from you right it has to be seamless
3:36there has to be a common framework and
3:37that really is what happened in 2010
3:40when a company called word nick decided
3:42to solve this was actually creating a
3:44restful interface sort of like the
3:46equivalent of soap in soap called wisdom
3:48and what this interface does is it not
3:52just allows it not doesn't just act as a
3:54common framework for all of these
3:56different teams working together to like
3:58build EAP iso acting like say a template
4:00or a blueprint for your api but also it
4:03sort of acts as an interface of sorts
4:05for your api so think like sort of like
4:07um not a GUI per se but really an
4:09interface not it doesn't your api is no
4:11longer a black box there's actually a
4:13restful interface that allows your
4:15clients to actually interact with the
4:16data or the service you want to expose
4:18and this was this is what this is this
4:22is the swagger specification this
4:23restful interface now now it's called
4:25the open API specification it was
4:27formerly called swagger specification
4:29and adalah and this is a human and
4:32machine readable API interface purely
4:34for rest rest based services that allows
4:38humans to implement API code that allows
4:41consumers of the API to read and
4:43generate API documentation as well as
4:45test cases against wares API resources
4:47and also because it's both human and
4:49machine readable it acts as an interface
4:51of sorts not just for internal systems
4:53but also for your teams to work together
4:56so the open API specification is now the
5:00industry standard in how restful epa's
5:03are supposed to be defined and so it's
5:06governed by the open API initiative and
5:08this is an open technical at this is a
5:11collaborative project under the Linux
5:12Foundation and you have all of these
5:14different companies working together as
5:16well as like the open source community
5:17in general and all of them are working
5:19together to like standardize the way
5:20restful api sort built and designed so
5:26while the open api initiative supports
5:29the specification you know and there's
5:31always this question what is swagger now
5:33well swagger is and always be the set of
5:36tools that's that's built around the
5:38implementation of the open API
5:40specification so you have the swagger
5:41editor swagger UI the swagger coach and
5:44we have swagger core and we have a bunch
5:46of the for another open source project
5:47if you can find a bit under the swagger
5:49github repository and all of them are
5:53essentially helping accelerate the
5:55implementation of the opening PS
5:56specifications so swagger Z are the set
5:59of tools that are built around the
6:00implementation of the open API
6:02specification so really quickly
6:06high-level you know what's new is we
6:08have some some great features you know
6:10there's improve reusability parameter
6:13changes there's improved examples as
6:15well as support for content negotiation
6:16and this is exactly what we will be
6:18covering in today's demo there are some
6:21additional advanced features like
6:22support for describing callbacks there's
6:24also a lot of questions on security we
6:26will not be covering this in today's
6:27demo and also of course links between
6:31different operations you will not be
6:33covering all these three sections in
6:35today's demo but we do have plans like
6:38go go into more detail in
6:41the upcoming webinars so I just want to
6:45quickly walk through some of the
6:48specification restructures and so this
6:51is how the open api 2.0 was right so
6:53this is swagger 2.0 you had it if you
6:57just look at it from a high level in
6:59terms of like the structure there was a
7:01lot of complexity to it right these
7:05there was now there's like structural
7:06changes in a bit to simplify the way you
7:08visualize how the open API spec defines
7:10an API the root level object objects
7:15such as definitions have been modified
7:17to be more and kept encapsulate you know
7:20bigger sections and the whole purpose of
7:24this restructure is to address the
7:25inconsistencies and behavior of root
7:27level definitions it also extends the
7:30opportunities so reuse different
7:33reusable syntax across multiple
7:35operations yeah so there's also the
7:39addition of servers as well to the root
7:41level identity and this replaces the
7:43host and base paths with 3.0 you can
7:46have multiple servers as well for
7:47different environments and we will show
7:48you all of these in the demo of course
7:52we have now we have the parameters as
7:54well so apart from like the regular
7:56query and path parameters which have
7:57been carry forward which have carried
7:59forward from swagger to point out open
8:01API spec 3.0 we also have the header
8:03parameter we also have cookies as well
8:08so open API lets you define headers as
8:11in like header parameters and also
8:12cookie headers multiple cookie
8:15parameters can be sent in the same
8:16header and this they can be suffered by
8:18semicolon in space and also instead of a
8:22big changes we'd there's no longer the
8:24body parameter from swagger to finals so
8:26when you're defining a post operation
8:28you don't have you don't do it you don't
8:30use a body of the body parameter it's
8:32been replaced with the request body and
8:36request body also allows you to send
8:38form data and finally of course these
8:41parameters are reusable and they can be
8:43specified as reusable components under
8:45on the component section and finally of
8:49course in this demo we will be covering
8:50content negotiation so you know the from
8:53swagger to final consumes and produces
8:55have been removed thus there was like
9:00basic content negotiation which was
9:02supporting 2.0 but OAS repoint know
9:04takes it a step further so you can
9:05define different media types in your
9:07various schemas and you can specify what
9:10goes into these different media types so
9:14there's also better file upload support
9:16so things like defining different media
9:18types and files uploading an array of
9:21files as present in OS 3.0 but this was
9:23not present in 2.0
9:24there's also you can also specify a
9:27range and responses so standard HTTP
9:29codes from 200 to 500 can be specified
9:32missile range so it's time for the demo
9:34and the way I'd like to structure this
9:37demo is really taking a hypothetical
9:40scenario so let's take for example that
9:42you know we're part of the smart bear
9:43company and we want to design an API
9:46that allows users to obtain information
9:49about the employees within the company
9:51or also post information about a new
9:53employee into the company's database
9:55right so think of this as an HR API our
9:59team you know because swagger hub
10:01because we won't we're gonna be
10:03showcasing some of our collaborative
10:05features you have the API designer the
10:08API documentation team and you also have
10:10any player development team so this is
10:13our team our objective is to build this
10:15HR API so from a planning perspective
10:17let's assume that we have one resource
10:20called the employee resource and we want
10:23to specifically show one is of course
10:25define a get operation under this under
10:27this resource that allows users to one
10:31is of course get is get the information
10:35of all the employees within this company
10:37as an array you know I knew kids but you
10:39can specify the page limit as well as
10:42the information limit using some of the
10:44query parameters you can also get
10:46information about a specific employee
10:47within from the company's HR database so
10:51here we're going to be showing a path
10:52parameter to do so and finally of course
10:54you can post information about a new
10:57employee and so we will be showing you
10:58how to create a post post operation
11:01using
11:01response body object in the rig we're
11:06gonna be doing this is using swagger hub
11:08so swagger hub is the API design and
11:11documentation platform
11:12let's build four teams to drive
11:13consistency and discipline across API
11:15development workflow so feet so we have
11:18specific proposition of features like
11:21you know allowing teams to standardize
11:23the API design across there across there
11:26across multiple teams centralized
11:28centralized collaboration on a secure
11:30cloud platform and finally order
11:32generation and hosting of interactive
11:35API documentation so let's get started
11:39so this here is swagger hub so I'm right
11:50now in my in the spider hub website or
11:53the app I've logged in so you can see my
11:55login information right over here and
11:58what I'm gonna be doing over here is if
12:02you can note if you see over my screen
12:03there's like the left panel is the my
12:05hat hey sorry folks I see that we're
12:11seeing some people saying that they
12:12can't see ketchup screen and we're gonna
12:14work to resolve this quickly hey folks I
12:18hope everyone can now see my screen so
12:21yeah so sorry about that
12:22so this here is the swagger hub
12:23interface so if you'll notice on the
12:26left hand side this is the left
12:27navigation panel and this is where you
12:29can quickly access some of the EPS which
12:32you've worked on so for example there's
12:33the my hub section where you can go in
12:35and look at all of the EPS which either
12:37you've created so you can see all of
12:39these ApS that you've created or API is
12:41which you've collaborated on right so um
12:44so for example here occasion I need to
12:45this is an API which I created but
12:47there's also for example EPS which I've
12:49collaborated on so there's like the book
12:50API
12:51there's the inventory EP all of these
12:52ApS which I've collaborated on you can
12:54also search through all of the public
12:56API is available on swagger hub so this
12:59over here for example this is you can
13:01they're their swagger hub allows you to
13:03host and allow make public ApS
13:06discoverable by not just your teams or
13:07your partners but also to the rest of
13:09the world if needed and so you can
13:11search the public ApS available so we
13:13have the uber API we have Instagram so
13:15a bunch of public API is available in
13:16Stockholm and finally of course you have
13:18the ability to define organizations
13:20within swagger hub so for example I have
13:22the smart bird software organization
13:24which I'm the owner of and you can see
13:26all the EPS with smart bird software's
13:27builds in the past so these are the API
13:29definitions which you've created and you
13:33can see and you can discover all of
13:35these API is really quickly for the
13:38organizations which you belong to so in
13:41our case again so let's get back to what
13:44we wanted to do is we wanted to build a
13:45new HR API in open API specification 3.0
13:50so let's do that real quickly so let's
13:52go to my let's click on the plus symbol
13:55right over here
13:55and let's click on create a new API so
14:02we're gonna be starting with open API
14:04spec 3.0 and we will be starting with a
14:06blank template so let's give this API a
14:11name so I'm gonna call this the HR API
14:14OS 3.0 just give a quick name version
14:20number of 1.0.0 I'm gonna give this API
14:23name a title so I'm gonna call this the
14:25smart bear HR API and then I'm gonna
14:30give this on a quick description here
14:33and I'll modify this once we go into the
14:35editor within swagger hub you have the
14:38ability to define privacy or visibility
14:40for an API so for example if you're
14:42creating an API firm for just
14:44consumption within your organization's
14:45like an internal API then you can set
14:47the visibility the private you also have
14:49the ability to create a public API for
14:51like consumption from the rest of the
14:52world so we always recommend that if
14:55you're starting an API from scratch even
14:57if you want to eventually transition to
14:59a public model like start make sure that
15:01it's in pry your visibility set to
15:03private just because you don't want an
15:05API which is unstable to be accessed by
15:08the rest of the world so in this case
15:10specifically I'm gonna send this to
15:11public so that you know while I'm
15:12working on this you anyone any of our
15:15viewers can come in and check us out I'm
15:18gonna send this to off the autumn walk
15:20the autumn acting features on a road map
15:22for open API spec 3.0 so we're going to
15:25send this to off for now and finally of
15:27course you can define the owner
15:29for this API so by default it's set to
15:31smart bar software you can change the
15:33owner to your personal account as well
15:35I'm gonna keep this set to my
15:36organization so now we are on the
15:42swagger hub editor where you can
15:44actually now go go in and start defining
15:46and building your your restful interface
15:49for the HR API so let's start by again
15:54so one of the things which I always like
15:55to do before I start by defining my API
15:58is like let's just lay out the metadata
16:00and some of the most important features
16:02for information for any API it's like
16:04apart from like the basic information
16:06like the version number and like the
16:08overall high-level description the also
16:10it's good practice and define the Terms
16:12of Service as well as the support
16:13contact and the license information for
16:15the API so let's just do that right over
16:18here so I'm going to define a better
16:23description just information of new
16:41employees right so this is just a
16:46high-level description on what we want
16:47this API to do let's give this the Terms
16:53of Service and in this case I'm just
16:58gonna go ahead and put down the
17:02smartbear.com use
17:19and then from here I'm gonna define the
17:20contact information so name here is
17:24gonna be me sure I can define a URL as
17:29well as if I have a pot if I have a
17:30website I can define that here I'm just
17:32going to define smartbear.com as the
17:34website name and finally of course I can
17:38put specify an email as well and here
17:40I'm gonna set my smart bear email
17:43account and you notice that as I'm
17:48typing it's getting automatically
17:50visualized on the right so you can see
17:51that all of the information I just put
17:53in has been visualized my slider hub
17:55automatically and every time saying I
17:57put in a deaf and I put in an object or
17:59like any other syntax which is not
18:01compliant with the open API standards it
18:03gives me an error with also like
18:04feedback on how to resolve it I'm also
18:08gonna put in some license information so
18:12this is just smart bear license and URL
18:18in this case I'm just gonna put in smart
18:24bear these URLs don't exist license calm
18:37so yeah so this is just like some basic
18:40groundwork before you go go ahead and
18:41define your API further so one of the
18:44big features in the open API spec 3.0 is
18:47the ability to actually define multiple
18:49servers right up so it's 2.0 you had the
18:51ability you can only set like one host
18:53and base path or one server for your API
18:56in 3.0 you actually have the ability to
18:58set multiple servers so say for example
18:59you have the API definition that exists
19:01in different environments you can
19:02actually actually define this as well
19:05so let's actually do that and service
19:08goes into the root
19:23consistent to find this sort of I can
19:29just use food calm for now and
19:33description this is the dev server for
19:38the API and same thing I'm going to
19:43define another server
20:08you go safe so we're defining the
20:12opening Claire specification in the ammo
20:14and yanil is very particular about
20:16indentation so one of the
20:17recommendations is always make sure that
20:19the indentation is correct and again do
20:22the open API standard we've recommend
20:25that Yama will be the way in which you
20:27define an API just because it's more
20:28human readable than JSON so now let's go
20:32ahead and start defining our first
20:34resource which is the employees resource
20:36and again if you remember recall our
20:38objective objective is to allow users to
20:42get information about existing employees
20:45within the company's HR database so
20:47let's go ahead and do that so I'm gonna
20:53define my employees resource right and
20:57under this I'm letting defining my first
21:00endpoint sorry for my first method which
21:02is the get method let's give a
21:06description for this does get matter the
21:09more information you can give about the
21:10API the better because that's the whole
21:12purpose of the open API specification is
21:14apart from the Russell interface it's
21:16also making sure that it's also allowing
21:19your consumers to get rich information
21:21about how to consume your API HR
21:30database and and if you recall one of
21:33our we also want to make sure that we
21:36have the right parameters so let's
21:37define two query parameters one which
21:39I'm which allows your end consumer to
21:42define how many employees they want
21:44returned and then the second one which
21:45allows users to define how many pages
21:48they want this information so we were
21:50chartered so let's define parameters I'm
21:56gonna give my first time at a name it's
21:58gonna call this body limit this is gonna
22:03be a query parameter so I'm going to
22:04define this as a quake it this is
22:06defined with the in object it's again
22:09give it as many descriptions as possible
22:11so
22:18and then finally one of the big
22:19differences as well when you're defining
22:21api's from 2.0 to 3.0 is the usage of
22:24the schema object so there's a common
22:27and you'll see this pattern as we as we
22:29design this API further you'll see the
22:31schema object being referenced a lot so
22:33we're gonna which essentially allows you
22:35to define what specifically like are
22:37this specific parameter is so here I'll
22:41show you exactly what I mean so under
22:43the schema object you will be defining
22:45things like what type of parameter it is
22:49you also define say things like the
22:51minimum so let's say the minimum here is
22:54gonna be 10 the maximum we want maximum
22:57employees we want return but with any
22:59specific API call those 20 and we can
23:02also define an example so let's say
23:04example is 15 right so this is and again
23:10we're getting the an error right now
23:13because we haven't defined our responses
23:14yet so we're gonna find our first query
23:20parameter which is the body limit Cripe
23:22parameter and which defines how many
23:24employees you want returned let's define
23:26our second parameter and I'm just gonna
23:27copy paste this real quick and let's
23:39call this page limit and here we want to
23:44say the pages
23:55employee whoops right and let's just say
24:03over here that the maximum pages we want
24:06return at any given point is five the
24:08minimum is one and an example of this is
24:11to write so we've defined to us our two
24:15parameters so we've defined two Kray
24:29parameters so now let's go ahead and
24:31start defining our responses so in this
24:33specific response I want to define a 200
24:36response and in this 200 response
24:38I wanna in my response on body which is
24:41going to be an array of employees I want
24:43to give the ID if the employee and the
24:46employee title so let's go ahead and
24:49define our responses and again this the
24:51response should be in the same level as
24:55the parameters so make sure you're on
24:57the same level there and when the spider
24:59how about it so you can actually see
25:00which lioness with the lines over here
25:03so hopefully you guys can see my screen
25:07responses right so let's define our 200
25:10response and this is again standard HTTP
25:12error codes or status codes description
25:29and now let's define what are the odd
25:32objects you the array of objects you've
25:34got you're going to get returned so this
25:37is where the content negotiation part of
25:38the open EPS that comes in and I'll show
25:41you what I mean so you can actually
25:42instead of defining directly the body of
25:45the responses you actually define start
25:47with the content so the type of media
25:48like the type of content you're going to
25:51be receiving so in our case let's say we
25:53want to define this in JSON right so
25:56application JSON
26:01and under application JSON again we're
26:04gonna be calling the schema and if you
26:06recall the schema schema what the schema
26:09does is it defines it defines the
26:11content little more like so we're gonna
26:15called say this is an array and the
26:19items you're gonna be getting out of the
26:21array and again if you're defining an
26:23item in a way you have to follow that up
26:25with the items involved in the area so
26:29let's define all the properties under
26:31this and I'll describe everything which
26:34I'm doing again just so that we can can
26:37be sure from this so just to recap what
26:40I'm doing right now I'm defining the
26:42successful response which is a 200
26:44response and I'm defining that the
26:46response is gonna give back and a JSON
26:49array and in this JSON array I want to
26:51define I want to say that you're on a
26:54successful call consumers are going to
26:56be getting the ID of the employee in the
26:58name of the employee and the title of
26:59the employee so let's define that so
27:03this is the first in information one
27:07second
27:18so yeah so we're defining the ID which
27:22is an integer let's give an example of
27:28this which is 4 right so I'm defining
27:31again my first endpoint and my first
27:35response object which is the ID and
27:39let's go in and define our second
27:42employee name this is going to be a
27:47strength again and an example of this is
27:52say Ryan Pinker and finally let's give
27:57employee title type of this is string an
28:04example of this is its market right so
28:18what did I do over here well let's let's
28:21recap real quick so if we define our
28:23first resource which is the employees
28:25resource under this resource we define
28:27our first method the get method and form
28:30and again what we want to do is we want
28:31to define parameters and responses
28:33because that's what makes a basic API at
28:36the request and response cycles so the
28:38request cycles we have two parameters we
28:40have the query parameter both of them
28:42being query parameters the first
28:44parameter allows you to specify how many
28:46employees you want returned and over
28:48here the way we define it is 1 of course
28:50defining the name and what it is which
28:52is the Quai but also then whenever you
28:54want to describe something in terms of
28:56like what the type of parameter you're
28:58the type of object it is in general and
29:00with the examples as well as some
29:02constraints you use this the schema
29:04object over here so let me use schema
29:06and under this we define the type of
29:08some more details about the parameters
29:10in terms of like the data what is the
29:12datum what is the data structure what is
29:15what type of data it is what is the
29:18minimum and maximum as well as with an
29:19example
29:19same exact real logic for the second
29:22query parameter finally when we go ahead
29:24and define our responses we're defining
29:25our first successful response which is
29:27200 and then we have the introduction of
29:30a new object you know
29:31or knowledge is content and content
29:33essentially this is where the content
29:35negotiation aspect if it can come into
29:36the picture you go in from instead of
29:38defining the responses directly you
29:40actually go in and define first first of
29:43all the type of content you're going to
29:44be getting back so here for example we
29:46were defining application slash JSON to
29:49be the type of content and under this
29:50again remember schema is where you go
29:52ahead and define like the type of
29:54information are going to be getting back
29:56so we have the schema information over
29:57here
29:58we're calling this an array and under
30:01this we have the various properties
30:03which you use to then go ahead and
30:05define what that response object is you
30:08can always like this is just our first
30:10endpoint and so let's go ahead and
30:13define well this our first method so
30:15let's go ahead and define our post
30:16method now and of course if you go over
30:20here you can notice that whatever we
30:22just put in this information has been
30:23rendered now if you add more content
30:26over here so we have application JSON we
30:28can actually go ahead and put
30:29application in slash XML you'll actually
30:31see that being rendered so I can
30:33actually put real quick as well so we'll
30:41do that as you move forward I'll give
30:44you I'll show you an example when we go
30:45into the next phase of the design so
30:49let's now go ahead and define our post
30:50operation so again be careful about the
30:53indentation is awareness so this is
30:56where I define a post and no matter and
30:59under post I'm gonna be again describing
31:04as much as I can so
31:17mmm-hmm so so this is where again so
31:20this is a big change as well from 2.0
31:233.0 so when you're doing a post in 2.0
31:25you had the body parameter 3.0 is God
31:29done away with the body parameters and
31:31what we have now is something called
31:32request body this is just me this just
31:34makes it much more easier to define
31:36objects and we've also added I believe
31:39the file upload on the the form data
31:42under the request body object you know I
31:46know we have Ron on call if I say
31:48anything wrong let me know Ron it was
31:50the developer evangelist for swagger and
31:51open API so yeah so this is so we're
31:55gonna be now defining all of our the
31:57parameter image for the post parameter
32:00under the request body object so we then
32:05need to specify that this is a required
32:06entity so we say required true right so
32:10because the post requires that you
32:11actually post something so this is going
32:13to be true and again the same exact
32:15logic or the content negotiation part of
32:17it is you can now have to go and define
32:19what is that content you want to push or
32:21like post to that specific resource so
32:24over here the same thing let's define up
32:26to the application slash JSON let's
32:32define the schema which is defining what
32:36the type of information you want to put
32:38now when we when we post I don't want to
32:40post an array I want to post
32:41specifically just one employee so I'm
32:42gonna just do the post an object so
32:45instead of array I'm gonna say this is
32:46an object and now let's define all the
32:51information that goes in the post right
32:52so same whatever we posted or whatever
32:55information we get back we won't also
32:56post all of that
33:11second my computer screen a stock okay
33:25sorry about that seems to be a little
33:41problem my browser let's give me a
33:43second
33:51yeah perfect so we just defined what is
33:55the content which gets posted and again
33:56I just copy pasted all the information
33:58you get back in a specific in when you
34:01actually make a successful call so the
34:03ID the employee name and the employee
34:04title I'm only saying that you when
34:06you're posting a new employee
34:07information these are some of the things
34:08you need to have which is the ID the
34:10employee name and the employee title and
34:13of course every by default every
34:15operation requires that you also have a
34:17response so this response is in the same
34:21level as the parameters or in this case
34:24the request party which is a parameter
34:26of sorts right and under this I'm gonna
34:30be specifying or 200 response so yes
34:37sorry this I put in a request it should
34:39actually responses yep so yeah so we
34:42just defined our first pet a post method
34:46as well so just a quick summary we this
34:49is a very simple API lets me show the
34:52split view all as if now what we did is
34:55we define a first get operation under
34:57the employee resource we define the
34:59parameters that go both of them are
35:01query parameters and we define what the
35:03successful response is when we actually
35:05get this information and then we're also
35:07defining a post method on under this
35:10resource where you can post information
35:11about a new employee in the system so
35:13I'm defining the ID the name of the
35:16employee in the title of the employer
35:18and responses which I am in defining
35:19under this is 200 is is just a basic
35:22success to a successful response India
35:25in though in the real world of course we
35:26recommend defining as many whatever
35:29those responses your API supposed to get
35:31so here and in this example I'm only
35:32defining 200 responses ideally what you
35:36should be doing is defining even like
35:38the other responses like the for
35:39hundreds or the 500 which are APR
35:41potentially Gibbs so let me save this
35:46and now let's go in and define our next
35:51method I saw your next resource which
35:54was which is gonna be a path parameter
36:02right so here I want to say that I want
36:04to get information about a specific
36:06employee within the company so here I'm
36:11gonna define get let's see if everything
36:16is in terms of like the structure here
36:19right and over here let's change
36:27information about specific employee and
36:37over here what I'm saying is now if say
36:39for example someone puts in the ID in in
36:42their request if this I have someone
36:43specifies the ID of an employee they
36:45should be getting information about that
36:47employees about that specific employee
36:50from the from the API so I'm gonna be
36:53specifying for this a pad parameter the
36:59name of the parameter is called ID
37:03required yes we pass parameters like
37:06request bodies need to be need to be set
37:09to true from the required perspective
37:10because again you need to specify this
37:12in order to get any sort of information
37:16we have to define what the specific path
37:19parameter so that's where the schema
37:21comes in so you define the type of this
37:25type of scheme is
37:32the you say specifically that this is
37:35the ID of the employee actually that's
37:38we should say that over here and then
37:44let's give an example as well before of
37:50course you're gonna be getting an error
37:51because you need to have responses as
37:53well so let's say that on a successful
37:55response you're only defining 200 s in
38:00this example let's give a description of
38:04the success and also as always define
38:11the content right and I'm gonna be
38:13exactly defining exactly all this
38:16specific information same exact content
38:18which on which we get right so we define
38:25it to be application JSON and then we
38:27defined specifically the schema there
38:29you go so we just defined our path
38:33parameter over here which was the
38:34employee slash ID which is where you
38:36actually can specify specifically which
38:38employees information want to get and
38:40use put in your request you put in the
38:42ID of the employee and you will be
38:44getting this is the ID of the employee
38:45and you will be getting all of the
38:47exactly if you see the example model
38:48over here you'll be getting all of this
38:50information so now I want to quickly
38:54touch upon if you look at this API you
38:57will notice that there's a lot of
38:58reusable components which we added
38:59specifically all of the responses can be
39:02reused multiple times across the right
39:04there's also specifically if you look at
39:06the post prime post method
39:10under the post operation in the request
39:11party you're essentially presenting back
39:13the same information you might be
39:14getting back on the secona on a get
39:16operation under the get operation so
39:18what you can actually do is define the
39:20components section where you can
39:22actually have all of this reusable
39:23components defined in a singular section
39:25that can be referenced across multiple
39:27operations or resources within the API
39:29so I'm gonna save this API I'm gonna
39:32actually create a new app add a new
39:34version to this API so let's call this
39:362.0 but then swagger hop saga has an
39:39internal versioning system so you can
39:41actually add multiple versions of the
39:42same
39:43and so I've added a new version you can
39:46toggle between one and two at any given
39:47point when I'm gonna be making my edits
39:49to the new version so just like make it
39:51more I would say it's simple to
39:53understand and make sure all of the
39:54reusable components are defined in a
39:56senior section so let's define let's see
39:59what are the common things we can define
40:01the first thing as soon as you based on
40:04what we just said and you know as soon
40:05as you start looking at this API
40:07specification one thing you'll notice is
40:09quickly you can actually define all of
40:11this the information like the ID the
40:13employee name and the employee tell the
40:14response objects as a common model which
40:17is which is what you we will be doing
40:19now so let's go in schemas and so we're
40:31defining this was instructor 2.0 this is
40:34called definitions the definitions model
40:37has been done with and it's been changed
40:39to components and now under components
40:41you have to define the schemas right so
40:43remember schemas is what what OS the
40:46users like define specifically the data
40:49type in the examples and some
40:51information on like whatever the model
40:52is so over here I'm gonna be defining a
40:55new model call employee write
41:00description over here is gonna be
41:04containing employee info and essentially
41:12what I'm going to be doing is I'm gonna
41:13be defining all of this information
41:14right so the properties and everything
41:17this for an employee I'm gonna be
41:19defining that over here make sure this
41:24is in Yama's and make sure all the
41:26indentations are right and notice that
41:31as soon as I type this it's been
41:34rendered on the right so I've just
41:36defined my first employee model and what
41:40I can do now is go in over here and this
41:46is our first information so let me go in
41:50right over here and instead of having
41:52the properties go in
41:55the dollar rough the syntax for this so
42:01if you do a dollar breath right and now
42:10what we're doing is now instead of
42:11defining all of those objects in the in
42:14the operation itself I'm going to be
42:15referencing this specific component so
42:17it's gonna be this is a syntax you're
42:20first gonna be pointing to the specific
42:22API which is done by the hatch and then
42:24it's going to go Traverse who the
42:28component section and under components
42:31they're schemas right and under schemas
42:34there's employee so I'm now referencing
42:45this specific component over here
42:48schemas so now let's go over here and
42:53see where else we can reference this
42:57there we go we can also reference the
43:00specific component in the post method as
43:03well so let's do that the same exact
43:08sense X I'm just gonna copy paste this
43:09and again we can see all of this
43:22information over here and and one of the
43:26things we can actually show off over
43:28here is also the content negotiation
43:30part of it so now I can actually define
43:32application say slash XML and as
43:37copy/paste the same exact and if you go
43:42over here
43:46you can actually select application XML
43:49application JSON and you can see how the
43:52response object would be so response
43:54party would be saying it's changing
43:55based on the type of responses you want
43:58back so I can click on save
44:03and you can do the same exact thing over
44:06here is you can in your post is you can
44:13just change this to XML and so you can
44:19go into the post and you can select what
44:22type of response bar even one no let's
44:25let's actually now go in and if you if I
44:27look at the responses in my first
44:31operation which is the ghetto operation
44:32for an array notice that this is
44:34actually asking for an array right and
44:37so what I can do actually is in my
44:39components itself let's define a new
44:44section called employees
44:47this isn't plural and this is where I
44:50can actually let I'm defining um an
44:53array of employees right so in my
44:55description you can call this an array
44:59of employee info okay I'm gonna define
45:04this to be type array and then my items
45:09in this is going to essentially be all
45:13of the information under the employee
45:15model so you can actually reference
45:17under components as well another
45:19component so so under my employees array
45:32the plural I am actually referencing
45:34this specific I'm saying all the items
45:38in that array is gonna be having this
45:39all of these properties so the ID the
45:43employee name and the employee title so
45:45I'm gonna be clicking on save and now I
45:48can actually go in over here to my first
45:52the first get method right and now in my
45:56responses which is an array of
45:58information about the employees I can
46:01actually just go in and under schema
46:12instead of all of this information all I
46:14do is type ref and opponents slash
46:24schemas slash employees second right so
46:43now you'll get all this we're now
46:44referencing the specific employees which
46:46is essentially an array of all of these
46:49all of the information in the employee
46:51model so you this is where you can
46:54actually be very creative and make sure
46:56that your API is is defined and in the
46:58most simplistic of ways but also in the
47:01way in which like all future definitions
47:02or for all future iterations of this API
47:04can be done in a much more quicker
47:06fashion so now when your other
47:08developers come in and add more updates
47:10this APR new endpoints new methods they
47:12don't have to constantly keep real
47:13dating adding new information they can
47:15just keep referencing the components
47:17part of it so the one thing so this
47:21really is so we've done a lot behind I
47:24know we were short of time so you know
47:27we've gone from actually going in and
47:29defining say specific we've done we've
47:32defined to specific resources one is of
47:34course the employees resource where we
47:36go in and we defined two set of
47:38parameters both of which are query
47:40parameters and we've shown you how you
47:43can actually go in and do and actually
47:46specify different information about
47:48these parameters under the schema
47:49section and the schema section is again
47:51the same how the OAS v-point know what
47:54the OAS 3.0 uses to define information
47:56about any request or response party
47:59right so we've done that we've shown you
48:01how you can actually define the 200
48:04response she let me show it this is in
48:07into 1.0
48:11right so you can actually define the 200
48:13response again we also showed you the
48:16post method and under the under the post
48:18method we showed you a new object called
48:20request body which is new to OS 3.0 you
48:22can define what you want to post and
48:25finally of course even we showed you the
48:28path parameter which is how you can
48:30actually get information about a
48:31specific entity in this case a specific
48:33employee then finally in our version 2.0
48:37of this API we actually made this API a
48:40little smaller but a little more elegant
48:42for future iterations by defining all of
48:44our common information under reusable
48:47sections called components you can also
48:49be more creative for example you can
48:51define your parameters as well under the
48:52components section you can end for
48:54referencing you can also for example
48:56define your responses as well under
48:59components but in this example I'm
49:01keeping it short by just defining just
49:03these common models the other big
49:05feature which I want to quickly touch
49:06upon is how so I in swagger home you can
49:09actually take an existing API in 2.0 and
49:11convert that to 3.0 so I have over here
49:14say an existing HR API which is defined
49:17in 2.0 which is exactly essentially the
49:19same thing which I just showed but in
49:202.0 you can actually go in over here and
49:23if you click on the top right corner you
49:25can actually convert this to open API
49:273.0 so swagger hub is one of the first
49:29tools to actually not just support open
49:31e pets like 3.0 in terms of designing
49:33and documentation but also conversion so
49:35once you click on conversion you know
49:37you can you have this option to convert
49:39so I'm going to click on convert and
49:41update and you will see that all of this
49:44API is now converted to the open e
49:46inspector you point oh and of course
49:48you'll have to go in and potentially add
49:49a little more definitions or make it
49:52more concrete like in terms of
49:53descriptions but for the most part this
49:55is our conversion was very seamless and
49:57works almost instantaneously
50:12so that brings us to the end of our demo
50:16I know we have no we have about 10 more
50:21minutes for Q&A five to ten more minutes
50:23but these are just the resources which
50:25you can use one thing I do want to bring
50:26the point out is that we have a very
50:28very concrete documentation portal on
50:31swagger area where we've documented not
50:33just the usage of the open API of the
50:35swagger or open source tooling but also
50:37the but also open API spec 3.0 and this
50:41is I think the only comprehensive one of
50:44the few only comprehensive documentation
50:46that exists for the open API is that we
50:48point O so please do check it out shout
50:51out to our documentation team until
50:53who've done this who done a great job in
50:54documenting the open e cares like 3.0
50:56soonest it came up oh yeah if you if
50:58you're interested in learning more
50:59please feel free to use that resource
51:01and swagger hub they're always there we
51:03have our resources we have an active
51:05blog where we continue to support the
51:06latest and greatest in technology so
51:08hand it over to Ryan for like questions
51:14thanks so much we did receive a ton of
51:18questions during today's webinar and we
51:21did our best to get to as many of them
51:23as we could we a for anyone the Mary
51:27we'll just cover here or didn't get to
51:28in chat we'll do our best default with
51:30everyone to get your questions answered
51:32one of the questions that come through
51:34with someone who seems to be just
51:35getting started they want to know I'm
51:37when we recommend starting with three
51:40dotto or made sense and maybe start out
51:42with gyro and then move to three doe
51:44things should be probably pretty
51:45straightforward answer but figure thing
51:47up yeah I mean I think that's a very
51:49subjective question as of not like 3.0
51:51is great for my buddy it has it adds a
51:54lot of rich expressive powers for
51:57actually defining an API that that makes
51:59it really great but again one thing is
52:01of course like if you really want that
52:03concrete tooling as well like 2.0 has
52:05been and has been an established
52:06framework which has a lot of tooling
52:08built around it right and so a lot of
52:11swagger open-source flowing as well
52:13which has now transitioned into 3.0 so
52:15it really depends on which stage of the
52:17lifecycle you're in I would
52:18say that you know 3.0 is just great
52:20lakes just it's to describe any pn them
52:22in probably the best expressive way
52:24possible but again if you're looking for
52:26more tooling to like fully utilize the
52:28power of 3.0 then a lot of tools are
52:31still coming out to like you know
52:32implement in the opening has my dream
52:34you know so that's just my
52:36recommendation defining the api opening
52:38aspect we point out but if you also want
52:40to take this in excel and harness some
52:42of your open source as well as
52:43commercial tooling out there to like
52:44really take this to the next level you
52:46know maybe we might hopefully we will be
52:50seeing more much more to like to come
52:53out and like support this one thank you
52:55and can you put different content types
52:59in one response that you're defining yes
53:02you can you can specify it like
53:05application json xml even images i
53:07believe in different responses as well
53:10as request bodies so yeah you can
53:12definitely do that which is what we also
53:14build this in the demo as well so we
53:16define application JSON we also did in
53:18the file XML so this is one of the new
53:20features which has been added to okay
53:23now can i define some object like a
53:30class and further user as a reference
53:33[Music]
53:36that I know is Ron on Ron's on the lines
53:40of I don't really know you may not be
53:45able to get to jump in on that one we
53:47have to go back to that one
53:48the other question we had was around
53:51mechanisms to verify that uh OS 3 data
53:55of specification is actually up-to-date
53:57I know that's something that you know
53:59we've validate it'll validate within
54:01your spat correct yes so with swagger
54:03hub automatically validates your API to
54:05make sure that it's compliant with the
54:07open API standards right so we whether
54:09it's 3.0 or 2.0 you know you'll always
54:11get like that error validation swagger
54:13poppins also actually work if you're
54:15actually actively working to like
54:16release our style validator as well
54:17specifically for the opening I expect we
54:19point oh so within your organization's
54:21say for example you have specific styles
54:23or guidelines which you want your API to
54:25follow then or like your designed to
54:28follow then you can have that specified
54:30in our style guide as well and that's
54:31something we're actively working and you
54:36did show this quickly at the end there
54:39but someone was asking if they have two
54:41of those specs what's the best way of
54:43kind of get started on converting those
54:44to 3.0 so I think if you're using
54:48swagger up today we do have the ability
54:50to do that and you can convert your
54:53specification over we did get a lot of
54:55questions as well about importing
54:57existing swagger files into swagger hub
54:59if you aren't using a platform like
55:01swagger hub on your using to do a spec I
55:04mean I think porn things are using some
55:06of the takeaways from today's sessions
55:07then maybe have to go back and
55:09reconfigure your existing spider
55:11definition I'm I don't have anything
55:13else to add to that one of the cool
55:15things about the conversion is now
55:16instead of like going line by line in
55:19your existing swagger 2.0 spikes and
55:20like converting each and every line or
55:22like seeing if you're it's compliant
55:23especially if it's like a long API which
55:25has like over 500 lines which is a lot
55:27of API sand in the ecosystem as of now
55:29you don't have to do that manually you
55:32can actually import that directly to
55:34starter home so we have an import
55:35capability within slogra home where you
55:36can just import an existing API this is
55:39a 2.0 and then convert it to 3.0 using
55:41our autocut our conversion feature
55:43awesome we did get a lot of questions
55:45around different tooling and we'll have
55:47support for oai 3 dot
55:49it is important to point out that you
55:51know here's part of the swagger team we
55:53are actively involved in the development
55:56of the new spec and certainly they focus
55:58on the tools but we won't necessarily
56:00have insight into some of the other
56:01tools that might be out there that are
56:02beyond the initial swagger tooling um if
56:05you do want to learn but the latest
56:06open-source tools that support that we
56:08do have some information on our swagger
56:09bio website and there was a lot of
56:11specific questions around the square Co
56:13gen tool I did check with the team and
56:15they will be releasing the first release
56:17candidates before the end of October to
56:20get your feedback and then I would
56:21expect you'll see that within swagger
56:23hub hopefully by the end of this year
56:25let's see if we had a couple different
56:29questions uh yes so we had one there was
56:41a couple questions that are coming in
56:42and folks are asking us to go back to
56:44some of their questions so you may just
56:46need to put them in we are just throw up
56:47time but if you are asking us to revisit
56:49your questions I'm sorry if I didn't
56:50miss them we will get our bet do our
56:53best to get back to those let's see if
56:55we have time for a couple more someone's
57:00asking around for the use of the links
57:02section for documentation I know you
57:06touched on links a little bit but maybe
57:08it's all from a documentation standpoint
57:10um the use of those in three oh yeah
57:12definitely so that's one of the things I
57:13highlighted initially is that that's
57:15that's something we're not planning on
57:16like taking a deep dive in our upcoming
57:18webinars linking is something which you
57:21know it's so it's a very touchy topic
57:23because you know it's not directly
57:24hypermedia but it also helps in some
57:27high-level way so that's something we
57:31definitely want to touch upon in our
57:32upcoming webinars in this webinar IV we
57:35didn't want to touch on it just because
57:36it was it felt like a more advanced
57:38topic but if you're very interested in
57:40like learning about in a linking please
57:41feel free to go to swagger bio slash
57:43talks you'll see the specification
57:46documentation and right there on the
57:47left we will see the linking section
57:49link sections where you can learn more
57:50about how links work and OS 3.0 and
57:57someone was asking it looks like it's
58:00the first time seeing the swagger hub
58:01platform
58:02can close on this question and I know we
58:04did have we're still seeing questions
58:06come through so we are trying to take
58:08them out this weekend and we will do our
58:09best to answer these questions in the
58:10follow-up blog post or made a video or
58:12in another webinar so thank you for
58:13funders to be putting your questions but
58:15specifically you know why did we show
58:17swagger hub maybe you know they're
58:20usually using the swagger tooling today
58:22and why would they want to use Swire hub
58:23over some of the swagger editor I what
58:27people using the editor of the UI today
58:30yeah that's a great question so you know
58:32the the open source tools are great for
58:33like doing specific job functions like
58:35for example the swagger editor is like
58:37really great for like going about
58:38designing concrete awesome api's both in
58:41OS 3.0 as well as swagger you have the
58:43swagger UI which is a section which is a
58:44another tool to like generate
58:46documentation you have the code gent
58:48like generate code and then of course
58:50you have to go in and build your own
58:52infrastructure like host all of this
58:53documentation as well as provide the
58:55right access control specifically to
58:56different API is you know based on
59:00whether it's a private model or a
59:01partner model or even internal model a
59:04complex model what swagger hub does is
59:06essentially takes the best of all of
59:07these open source tools adds another
59:09layer of features as well as removes all
59:12of this infrastructure complexity of
59:14hosting and generation of code as well
59:17as documentation and essentially allows
59:19you to go from planning all the way to
59:20documentation as well as generating code
59:22and the quickest and easiest way
59:23possible the icing on the cake is
59:25collaboration so we we know that API is
59:28especially API is no:1 it's well ats
59:32building api is a collaborative process
59:34you know as we mentioned before like it
59:36goes from architects developers testers
59:38deployed devops
59:40documentation writers all their
59:41different job functions all and all of
59:43these people have to work together to
59:45like build a great API and it starts
59:46from the EPS design and so swagger hub
59:49offers a very collaborative tool to like
59:51to essentially allow you to deployed and
59:54deliver great grade ApS in the quickest
59:57way possible while also ensuring quality
59:59near API is by standardization of design
1:00:01across your rigorous API is for your
1:00:03teams so that really isn't a nutshell
1:00:05why why what what's the power of swagger
1:00:07apart from you know all of the regularly
1:00:09bringing together the open source tools
1:00:10as well as auto-generating and hosting
1:00:12the documentation
1:00:16often thank you so much unfortunately
1:00:18our a little overtime here guys we are
1:00:21gonna have to wrap up I do still see
1:00:23questions coming in from Ronan William
1:00:27Peter sorry we weren't able to get to
1:00:29all of the questions there were some
1:00:30questions that came in that we do need
1:00:32some more time to meet with the team to
1:00:34get some insight on so we will do our
1:00:36best to answer all those we appreciate
1:00:38you taking time out of your schedule
1:00:39today do feel free to send any feedback
1:00:41on today's session or any other further
1:00:44questions and as I said we'll do our
1:00:45best to get back to it
1:00:47I'd like to thank Asia for the great
1:00:49introduction to OS 3.0 and thanks again
1:00:51for everyone who tuned in and best of
1:00:53luck billing API is with the new spec so