Creating Swagger Specs Document - Part 3
Tags: documentation, tutorial, api, swagger
Published: 2023-02-07 01:44:22

On this document we will continue writing the specs of our API that we started working on in my [last post](https://dev.to/alcb1310/creating-swagger-specs-document-part-2-5hhn) 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

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zd7siqf1zt86gvlp5920.png)

## 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

![users definition](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qpqqczccukpw4pqg1mvc.png)

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

![error message](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0z4osowr8p3o366fa59r.png)

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

![Parameters](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gods8ti3t3uxa9dxcm3w.png)

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  

![GET specific user](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/i61mlnt1e6slk2z5rbhs.png)

3. 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

![Delete](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6atejur9qbp2rws5krze.png)

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

![Delete security](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bmf5e2tfxhdlac6mh17h.png)

It is important we use the proper response codes, for that we can check the different [http status codes](https://www.webfx.com/web-development/glossary/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

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nq0ypnxd1eqjf1c5u49u.png)

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

2. 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

![PUT request](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/r0ya6jhu1pbem8p9ykjg.png)


## 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

![Query parameters](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0paj9grcr59iwfrbwqvk.png)

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