Creating Swagger Specs Document - Part 3

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 added the get all users and create user routes, so this is what we've got so far

Adding item specific routes

Now we are going to write the routes that are item specific, meaning we are going to read one user, update a user and delete a user, all of them using the user id to search for it.

GET request

1. First in the paths section, we add the item specific route

Important to use the curly braces when defining path parameters. In this case we are saying to use the /users end point and that we will be passing the user id as a parameter in the path.

However when we save we get the following error

1. Lets handle that error, we need to define the parameter. Inside the get route we create the parameters definition

Here we have several new things we need to check

• in: path We define that the parameter is part of the path
• name: id We define the name of the parameter which has to be the same as the variable in the curly braces
• required: true We define that the parameter is required or not

1. Finally we define a new response we can have, a 404 not found when a user with that id does not exist, also a 400 if the user id is invalid

DELETE request

1. Lets add the delete method in the user specific section

Since we want only an authorized user to be able to delete users, we specify that the user must be logged in to do so by removing the security property, we make sure that that is the case by the lock shown next to the delete method

It is important we use the proper response codes, for that we can check the different http status codes. Since there is no content for a successful delete we return a 204 no content response.

PUT request

1. Lets add the put method in the user specific section

Don't forget not to add the security property so only authorized users may update a user's information

1. Lets add the body of the request, what we will be receiving to update a user information. For that we just add the requestBody property we used in the POST method

So this is what the put request will look like

Final steps

Well after we have defined all of the users endpoint operations, we just need to define some constraints we can pass through query parameters to the GET all request, for example we can define we can add pagination, search, sorting capabilities, etc.

So lets add the pagination capabilities:

1. Under the GET all route we add the parameters property and define both page and limit parameters

being in query parameter means that will go after the question mark symbol (?) in the url and each parameter is a key value pair separated by an equal sign (=)

So the url will look something like this

https://virtserver.swaggerhub.com/alcb1310/New_API/1.0.0/users?page=1&limit=1

Next steps

What to do next

• you can define the todos endpoint like we defined the users one. Please share in the comments your version of it, will love to see your ideas.

• add the swagger definition to your express server so it will be easier to share your API documentation

• code your express server so it will reflect what we've designed