In the previous post, I introduced Swagger and showed how to set up your project for Swagger. In this post I will show how to add Swagger comments to annotate your program.
In earlier posts we looked at the database of cars and the Get method that retrieves the entire list. That can be quite a lot of data going over the wire. What we want instead is to send pages. I’ll show that briefly and then we’ll annotate that code.
In the CarController we’ll have a Get method that takes three parameters: showDeleted, pageNumber and pageSize. The first we’ve seen before, it determines whether the list returned to the caller will include our deleted records. The second, pageNumber, will designate which page of data we want to return (zero based). The third parameter, pageSize, will designate how many records to return per page.
Thus, if we were to write
Get(false,3,4)
we would expect to get back records 17, 18, 19 and 20, because page 0 would have records 1-4, page 1 would have 5-8, etc.
Here is the compete endpoint that will directly call our repository (we won’t bother with a service for this example).
public async Task<IEnumerable<Car>> Get([FromRoute] bool showDeleted, int pageNumber, int pageSize )
{
return await _carRepository.Get(showDeleted, pageNumber, pageSize);
}
When the repository is called, the parameters are passed in, and it does its magic. For now, however, we are only concerned with documenting this method. We do that with XML comments, designated by three forward slash marks (///).
First, we will document the purpose of the endpoint; that is, what it does. We do that in the summary
/// <summary>
/// Get all the cars in the Database
/// </summary>
Next, we want to document the parameters
/// <param name="returnDeletedRecords">If true, the method will return all the records,
/// including the ones that have been deleted</param>
/// <param name="pageOffset">which page to display</param>
/// <param name="pageSize">how many records to display per page</param>
Finally, I’m going to document the possible response codes. Note, these are, by no means, all that you can document, but they’ll give us a good idea of how it is done
/// <response code="200">Cars returned</response>
/// <response code="404">Specified Car not found</response>
/// <response code="500">An Internal Server Error prevented the request from being executed.</response>
When an error is encountered and we return one of these codes, the text we’ve specified goes along for the ride, which is enormously helpful to the calling client.
At the top of the swagger page is our summary
At each parameter is our designated text
Finally, each of the error codes is documented
It is a best practice to document all of the endpoints. Many developers go further, and document all of the methods in both the service and the repository; that is a decision to be made by the team. Since the endpoint is the only thing visible to the client, it has the greatest claim on your time and effort. Remember, “comments rust,” and that is as true for Swagger comments as any other.
https://lordfiilm14.ru/stati/stavki-na-sport-vsjo-v-odnom-meste-bkradar-kak-nezavisimyj-portal-o-stavkah-na-sport/ – лучший сайт рейтинга букмекеров и ставок на спорт по мнению людей 2026
Hey I know this is off topic but I was wondering if you knew of any widgets I could add to my blog that automatically tweet my newest twitter updates. I’ve been looking for a plug-in like this for quite some time and was hoping maybe you would have some experience with something like this. Please let me know if you run into anything. I truly enjoy reading your blog and I look forward to your new updates.
Aw, this was an incredibly nice post. Taking the time and actual effort to generate a top notch article… but what can I say… I procrastinate a lot and don’t manage to get anything done.
Currently it looks like WordPress is the top blogging platform available right now. (from what I’ve read) Is that what you’re using on your blog?
Hey I know this is off topic but I was wondering if you knew of any widgets I could add to my blog that automatically tweet my newest twitter updates. I’ve been looking for a plug-in like this for quite some time and was hoping maybe you would have some experience with something like this. Please let me know if you run into anything. I truly enjoy reading your blog and I look forward to your new updates.
Aw, this was an exceptionally good post. Taking a few minutes and actual effort to make a really good article… but what can I say… I hesitate a lot and never seem to get nearly anything done.
Excellent pieces. Keep posting such kind of information on your blog. Im really impressed by your site.
mostbet pul yechish Oʻzbekiston mostbet pul yechish Oʻzbekiston
Aw, this was an extremely good post. Taking the time and actual effort to make a really good article… but what can I say… I put things off a whole lot and don’t manage to get nearly anything done.
play luminous life slot game – play online casino South Africa
May I simply just say what a relief to uncover somebody that truly understands what they are discussing online. You certainly know how to bring an issue to light and make it important. More people need to look at this and understand this side of your story. I was surprised that you are not more popular given that you most certainly have the gift.
Great post, Jesse. I’ve been using Swagger for a while, but your explanation of how comments translate into the UI finally clarified a few points I was struggling with. Do you have any tips for keeping the documentation consistent across a large team?
Right now it looks like Movable Type is the best blogging platform available right now. (from what I’ve read) Is that what you’re using on your blog?
Народ всем привет Цены космос а качество мыло То кран-балки с зазорами Короче, мужики которые реально делают качественно — грузоподъемное оборудование Москва с доставкой Гарантия 5 лет В общем, смотрите сами по ссылке — кран балка подвесная https://tal-elektricheskaya.ru Проверяйте производителя по документам Перешлите тому кто ищет оборудование
Greate pieces. Keep posting such kind of info on your site. Im really impressed by it.
Wow that was unusual. I just wrote an really long comment but after I clicked submit my comment didn’t appear. Grrrr… well I’m not writing all that over again. Anyhow, just wanted to say excellent blog!
Hey I know this is off topic but I was wondering if you knew of any widgets I could add to my blog that automatically tweet my newest twitter updates. I’ve been looking for a plug-in like this for quite some time and was hoping maybe you would have some experience with something like this. Please let me know if you run into anything. I truly enjoy reading your blog and I look forward to your new updates.
Our Hobby Airport shuttle service to Houston hotels provides stress-free transportation for business and leisure travelers. Whether you’re staying downtown or near local attractions, we offer timely, comfortable rides to get you to your hotel without the hassle of parking or navigating Houston’s busy roads.
Hello there, You’ve performed a fantastic job. I’ll definitely digg it and for my part recommend to my friends. I am confident they’ll be benefited from this site.
You suggested that very well.
You stated this very well.
You said it well!
This post creates a easygoing atmosphere for discussion while still presenting the topic in a meaningful and easy-to-follow way.
Xxx video onlyfans sex video site
May I just say what a comfort to uncover somebody who truly understands what they are talking about online. You definitely realize how to bring a problem to light and make it important. More people should read this and understand this side of the story. I was surprised that you’re not more popular given that you certainly have the gift.
Hi there, You’ve performed an incredible job. I’ll definitely digg it and personally recommend to my friends. I’m confident they’ll be benefited from this web site.
Wow that was odd. I just wrote an very long comment but after I clicked submit my comment didn’t appear. Grrrr… well I’m not writing all that over again. Anyhow, just wanted to say fantastic blog!
I have read quite a bit on this general theme lately, but the way you have organized these specific points stands out as one of the most clear and well-structured overviews I have come across in a very long time.
viagra pills sexual xxx porn pills
Hey I know this is off topic but I was wondering if you knew of any widgets I could add to my blog that automatically tweet my newest twitter updates. I’ve been looking for a plug-in like this for quite some time and was hoping maybe you would have some experience with something like this. Please let me know if you run into anything. I truly enjoy reading your blog and I look forward to your new updates.
Aw, this was an extremely nice post. Taking the time and actual effort to generate a really good article… but what can I say… I put things off a whole lot and don’t seem to get nearly anything done.
Hey I know this is off topic but I was wondering if you knew of any widgets I could add to my blog that automatically tweet my newest twitter updates. I’ve been looking for a plug-in like this for quite some time and was hoping maybe you would have some experience with something like this. Please let me know if you run into anything. I truly enjoy reading your blog and I look forward to your new updates.
Грунт повсеместно применяется в сельском хозяйстве для культивации насаждений.
В закрытых помещениях грунт служит основой для зеленных культур.
На плантациях почва задействуется для посева зерновых и масличных растений.
грунт плодородный цена за куб
Грунтовые смеси нужны для создания газонов и садового обустройства.
В дендрариях грунт играет важную роль при производстве посадочного материала.
Кроме того грунт используется для восстановления деградированных территорий.
Субстрат активно применяется в аграрном производстве для культивации растений.
В парниках грунт служит базой для зеленных культур.
На открытых полях земля используется для высадки зерновых и масличных растений.
почвогрунт дмитров
Субстраты необходимы для устройства дёрна и ландшафтного дизайна.
В дендрариях грунт выполняет важную роль при выращивании саженцев.
Также грунт применяется для восстановления истощённых участков.
Субстрат активно используется в сельском секторе для культивации растений.
В парниках грунт служит базой для салатных растений.
На открытых полях почва задействуется для посева злаковых и технических растений.
чернозем красногорск
Почвенные составы нужны для формирования лужаек и ландшафтного дизайна.
В рассадных хозяйствах земля играет ключевую функцию при выращивании посадочного материала.
Также грунт используется для восстановления деградированных участков.
This post has a smooth flow of ideas that keeps the reader interested while also making the overall discussion easy to follow.
Xxx video onlyfans sex video site
ข้อมูลชุดนี้ อ่านแล้วเข้าใจง่าย ค่ะ
ผม ไปเจอรายละเอียดของ เนื้อหาในแนวเดียวกัน
ที่คุณสามารถดูได้ที่ Parthenia
สำหรับใครกำลังหาเนื้อหาแบบนี้
เพราะให้ข้อมูลเชิงลึก
ขอบคุณที่แชร์ เนื้อหาดีๆ นี้
และอยากเห็นบทความดีๆ แบบนี้อีก
Right now it seems like Movable Type is the preferred blogging platform available right now. (from what I’ve read) Is that what you’re using on your blog?
Hey I know this is off topic but I was wondering if you knew of any widgets I could add to my blog that automatically tweet my newest twitter updates. I’ve been looking for a plug-in like this for quite some time and was hoping maybe you would have some experience with something like this. Please let me know if you run into anything. I truly enjoy reading your blog and I look forward to your new updates.
The overall structure of this post works really well because it keeps the ideas connected smoothly and helps maintain reader interest from the first point to the last.
FEZ bet
Народ у кого дети в школе Вечные двойки и тройки в дневнике Ребёнок не высыпается Короче, реально удобный формат — онлайн обучение для школьников с реальными знаниями Уроки в удобное время В общем, жмите чтобы не потерять — сайт онлайн образования [url=https://shkola-onlajn-pqs.ru]сайт онлайн образования[/url] Хватит мучить себя и ребёнка Перешлите другим родителям
Hi there, You’ve performed a great job. I will definitely digg it and personally recommend to my friends. I’m sure they’ll be benefited from this website.
May I simply just say what a comfort to uncover a person that really knows what they are talking about over the internet. You actually realize how to bring a problem to light and make it important. More and more people have to check this out and understand this side of your story. It’s surprising you are not more popular because you certainly possess the gift.
At this time it looks like Movable Type is the preferred blogging platform available right now. (from what I’ve read) Is that what you’re using on your blog?
коттеджные поселки коттеджные поселки .
At this time it seems like Expression Engine is the preferred blogging platform out there right now. (from what I’ve read) Is that what you’re using on your blog?
ставки на спорт от лучшего сайта спорта и букмекеров bkradar.com
At this time it seems like Movable Type is the preferred blogging platform out there right now. (from what I’ve read) Is that what you are using on your blog?
Hey I know this is off topic but I was wondering if you knew of any widgets I could add to my blog that automatically tweet my newest twitter updates. I’ve been looking for a plug-in like this for quite some time and was hoping maybe you would have some experience with something like this. Please let me know if you run into anything. I truly enjoy reading your blog and I look forward to your new updates.
Народ у кого дети в школе Задолбали эти сборы в 7 утра Ребёнок не высыпается Короче, единственная школа которая работает — онлайн обучение для детей в комфортном темпе Уроки в удобное время В общем, жмите чтобы не потерять — онлайн обучение для детей онлайн обучение для детей Хватит мучить себя и ребёнка Перешлите другим родителям
Субстрат повсеместно используется в сельском хозяйстве для производства растений.
В парниках грунт является базой для овощных растений.
В открытом грунте почва задействуется для высадки кормовых и промышленных культур.
земля плодородная купить
Грунтовые смеси необходимы для формирования дёрна и садового оформления.
В дендрариях земля играет важную роль при получении рассады.
Помимо этого почва используется для восстановления нарушенных земель.
Hello there, You have performed an incredible job. I’ll definitely digg it and in my view suggest to my friends. I am confident they will be benefited from this site.