Creating Swagger Specs Document - Part 2

On this document we will continue writing the specs of our API that we started working on in my last post check it out so you will know how we get to where we are starting.

Last time we created our base Swagger Specs document and wrote the definition for the hello route

What are we creating

For us to continue and having a better understanding of the beauty and power of Swagger, lets first know what API is that we are going to be designing.

So we will be creating a simple TODO list API that can handle multiple users. We should be able to do the following:

• Users Route:

  • Create a new user
  • Read the logged in user information
  • Update user information - Can only update his/hers info

• Todos Route

  • Create a new todo item
  • Update the todo item: can either change the todo text or its status
  • Read all of the logged in users todos
  • Read the todo information of an specific todo item
  • Delete a todo item

Creating the Users Route

I've always use the same steps when creating a route and are the following:

1. Create the tag for the route's group:
   • In the tags section of the yaml document, add the tag with the name you want to use and also add a brief description for it, remember the >- lets you use multiple lines and markdown language to write your description. After you are done, your tags section will look like this:

1. Create the path under the paths section
   • In the tags section, add the path for the users route. After you are done, your paths section will look like this:

1. Under the responses definition we can add the content property where we define how the response will look like

this is how it will look once we've finish this

Now we've created the GET method for the /users endpoint, let's create the POST method

this is how it will look once we've finish this

This works perfect, however as you can see we are repeating the schema of the user response, with this we can make mistakes and describe incorrectly some of the response.

There is a better solution for this, and it is by creating schemas that we can reference through out our definition, so let's do that.

1. In the components section, lets add a schemas property, and inside it lets add a schema called **UsersResponse* where we will define the object as we did in both the POST and the GET response

1. Finally reference the schema in each of the methods, and we will get the exact same result

1. However we still got something wrong, is that in the GET request we want all of the users that are registered, so we expect to receive an array, so we just need to change that in the response

Finally in the documentation, this is how the GET and POST request will look like

Summary

In this post we've learned how to create GET and POST requests defining the schema information of what will be received and sent back to the user.

In the next post we will learn how to create item specific operations like the GET, PUT and DELETE