Create an API with Swagger

Will Button
InstructorWill Button
Share this video with your friends

Social Share Links

Send Tweet
Published 8 years ago
Updated 5 years ago

Swagger is a project used to describe restful APIs using the OpenAPI Specification. It allows you to document your API so consumers understand the endpoints, parameters, and responses. In this lesson, I'll show you how to install the swagger command line tool, create a new API project using swagger, and introduce you to the swagger API editor.

[00:02] To get started using Swagger, the first thing I need to do is install the package itself. It has a command line interface, I'm going to install it using the -g flag to install it globally.

[00:15] With that installed, I can create a new Swagger project using the Swagger command with Swagger project create, and then the name for my project, which is going to be todo-api.

[00:26] It supports multiple frameworks, including Express, Hapi, Restify, and Sales. I'm going to use the Express framework, and that's going to kick off the installation from the skeleton project. Switching over to my other pane, I can do a directory listing. There's a new directory called "todo-api."

[00:45] I can go into that directory, and then start my project using the Swagger project, start, and the name of my project. It gives us an example that we can use here to start it, we'll just try that over here in our other pane. It returns, "Hello Scott."

[01:04] The really cool part about using Swagger is that it has this editor that allows us to define our API. We can get to that using the Swagger project edit command. When I run that command, it opens up a browser for me, points it to localhost, and to a port that it's created to host this Swagger interface.

[01:27] Let's start looking on the right-hand side first. You can see that it has the name of our application, the version number, and then, it defines all of the paths that exist in the API. We've already used the /hello endpoint in our curl command that we did earlier, but it also allows us to use that from this editor, as well.

[01:47] It gives us a description about the endpoint, and tells us about all the parameters, a description, where it's located at, the type of data that it is. Same thing with the responses, and it gives you the details of the response that you can expect back from the API.

[02:03] We also have the ability to try it out from within the editor. It selects the scheme for us. Then, we can change the content type if we're selecting multiple content types. Then parameters, we can supply. You can see, as I supplied that parameter, it updated the URL that will be called with this.

[02:24] Then I can send that response, or send that request. It comes back with a success message. I can choose the output, and it shows the output from the API server. It's pretty cool. It allows you to test your API without actually having to have a specific client to do that.

[02:42] All of that comes from this definition over here on the left-hand side. Starting off, we've got the Swagger that defines the version of Swagger we're using. You've already seen the version number and the title that were displayed over here on the left, and the host name, as well, where the server's going to be running from.

[03:02] The most useful part of this is in this path section, where you'll define each of the endpoints hosted by your API. You can see one, the /hello endpoint that we used a minute ago. You can see how the description gets mapped over here to the UI provided to us.

[03:21] Other things to note here are the operation ID, which is the name of the function that's going to be called within your application to respond to this endpoint request. The types of responses that you support is defined.

[03:35] Then, there's this concept of definitions down here, where you can define a schema for the response itself. That's going to allow you to do some type validation on the responses that your API server is sending back down to the client so that as a consumer of this API, you can be confident that the data you're getting matches to the schema specification.

David
David
~ 7 years ago

I think there is something wrong with this lesson: there is no instructions on how to install the command line, neither an introduction to Swagger. However, in the RSS appeared a different lesson with the same title that shows you how to install the command line and give a better introduction than this lesson.

Will Button
Will Buttoninstructor
~ 7 years ago

Hey David, You're absolutely right! That's not the correct lesson. We're getting the correct one uploaded now. I'll update here when it's fixed. Thanks for pointing it out!

Will Button
Will Buttoninstructor
~ 7 years ago

Hi David, The correct lesson has been uploaded. Thanks again for pointing it out!

Olivers De Abreu
Olivers De Abreu
~ 7 years ago

Hi great tutorial, but I have the following question. When you are deploying to production how do you set the host and port variables?

For example in development you have in your yaml file http and localhost:10010 as your protocol, host and port, how do I change this to https and myapi.com ?

Do I have to use a nginx proxy server? It's there a way to do this with NODE_ENV variables?

Thank you

Will Button
Will Buttoninstructor
~ 7 years ago

Hey Olivers, For production: always use a proxy, either nginx as you mentioned or an ELB if you are using AWS. This allows you to load balance across multiple node.js instances, the SSL overhead can be handled by the proxy so you don't have to do it inside your node application, and you don't have to figure out how to get node to run as root so it can bind to the ports 80 and 443.

Olivers De Abreu
Olivers De Abreu
~ 7 years ago

Great thank you

Alexandr
Alexandr
~ 7 years ago

Hello, Will. Where is information about authorization and authentication? I not found it in lessons.But in course about section you say: "...Along the way, we will discover how to implement additional details required for a fully functional API such as authorization, authentication,..."

Alexandr
Alexandr
~ 7 years ago

Hello Will, where is information about authorization and authentication?

Alexandr
Alexandr
~ 7 years ago

Hello Will, where is information about "...authorization, authentication..."?

Jonathan Palma
Jonathan Palma
~ 4 years ago

If someone is receiving an "Error: Cannot find module swagger_router" using node 12, check https://github.com/swagger-api/swagger-node/issues/586 The user s-kalaus share this answer as a workaround

Problem is that in Node 12 Module Not Found error differs from Node 10. bagpipes relies on error message text. This can tepmorary be fixed in this file: node_modules/bagpipes/lib/fittingTypes/user.js file: var split = err.message.split(path.sep); should be var split = err.message.split('\n')[0].split(path.sep);

Jonathan Palma
Jonathan Palma
~ 4 years ago

If someone in Windows is receiving a " SyntaxError: Invalid regular expression: /.{1,0}/: " Try to use the CMD instead of another console, I received that error in git bash

sinewave440hz
sinewave440hz
~ 4 years ago

Little thing but may get you started quicker; some shells (zsh) currently require you to put quotes around the url in curl http://127.0.0.1:10010/hello?name=Scott

Amani
Amani
~ 4 years ago

For anyone who might be running WSL and run into issues with xdg-open - swagger project edit will crash, meaning the editor server doesn't start. You can run the editor without the swagger command attempting to open it in the browser with the --silent option. E.g. swagger project edit --silent. You should then be able to reach the editor by navigating to the host:port output by the command in your browser.

Jean-Michel
Jean-Michel
~ 2 years ago

Is there a way to use ES6 modules other than transpiling (with Webpack for example) ?

Markdown supported.
Become a member to join the discussionEnroll Today