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.
May I just say what a comfort to uncover somebody who truly knows what they’re discussing over the internet. You certainly realize how to bring a problem to light and make it important. A lot more people have to read this and understand this side of the story. I was surprised that you’re not more popular because you surely possess the gift.
Всем привет из культурной столицы Качество пластилин То фасады перекошены Короче, нашел наконец нормальную контору — кухни на заказ по индивидуальным размерам Проект бесплатно за час В общем, жмите чтобы не потерять — кухни на заказ в санкт-петербурге кухни на заказ в санкт-петербурге Проверяйте производителя по этому списку Перешлите тому кто тоже мучается
Слушайте кто недавно кухню делал. В Леруа Мерлен посмотрел — качество ужас. То сроки изготовления по полгода обещают. Короче, нашел наконец нормальное производство — купить кухню от производителя в спб из массива. Кромка на немецком оборудовании. В общем, жмите чтобы не потерять контакт — купить готовую кухню в спб от производителя https://zakazat-kuhnyu-rty.ru Не ведитесь на салоны в ТЦ которые просто заказывают у тех же китайцев. Сам столько нервов потратил теперь делюсь.
Currently it seems like BlogEngine is the best blogging platform out there right now. (from what I’ve read) Is that what you’re using on your blog?
сайт кракен darknet
Valuable write ups Many thanks. https://bit.ly/m/betflix
Aw, this was a very nice post. Taking the time and actual effort to create a top notch article… but what can I say… I put things off a whole lot and never seem to get nearly anything done.
May I simply just say what a relief to discover an individual who actually understands what they’re discussing on the web. You actually realize how to bring an issue to light and make it important. More people must read this and understand this side of the story. I can’t believe you are not more popular given that you certainly have the gift.
Проктологическое заболевание — это распространённая проблема, нуждающаяся незамедлительного лечения.
Отсутствие признаков или отсрочка визита к специалисту способно обернуться опасными последствиями, такими как выпадение узлов.
Текущая медицина располагает разнообразные методы коррекции: от малоинвазивных процедур до консервативной терапии.
проктолог онлайн
Ранняя помощь позволяет быстро устранить дискомфортные ощущения и восстановить качество жизни.
При появлении первых симптомов (зуд, жжение, следы крови) важно как можно скорее обратиться к проктологу для обследования.
Правильное воздействие не лишь избавляет от телесного страданий, но и предотвращает прогрессированию заболевания и потребности в оперативном вмешательстве.
Currently it appears like BlogEngine is the best blogging platform out there right now. (from what I’ve read) Is that what you’re using on your blog?
Thank you for compiling all these details into such an easy-to-digest format. The systematic layout and perfectly neutral perspective make this an outstanding piece of writing that genuinely helps readers understand the broader context of the topic.
Xxx video onlyfans sex video site
Wow that was strange. I just wrote an extremely long comment but after I clicked submit my comment didn’t show up. Grrrr… well I’m not writing all that over again. Regardless, just wanted to say great blog!
At this time it seems like Drupal is the best blogging platform available right now. (from what I’ve read) Is that what you’re using on your blog?
This is an excellent breakdown of the subject matter. I have been looking for a simple explanation without any unnecessary fluff, and your article provided exactly what I needed in a highly clear and completely balanced format. Great job!
retrait neosurf casino
indian pharmacy: indian pharmacy online – best online pharmacy
Excellent article. Keep posting such kind of information on your site. Im really impressed by it.
pin-up pul yechish http://www.pinup38742.help
Useful and straightforward content. Everything is explained clearly without unnecessary details.
Really appreciate your effort in creating valuable content. Looking forward to more posts like this!
Ударно-волновая терапия представляет собой современный способ воздействия, базирующийся на применении звуковых волн.
Данная процедура активизирует микроциркуляцию и запускает механизмы регенерации тканей.
УВТ часто применяется для терапии патологий опорно-двигательного аппарата – в частности, при тендинитах и плантарном фасциите.
https://novogireevo-klinika.ru/
Ключевые преимущества метода – это неинвазивность, практическая безболезненность и высокая эффективность даже после нескольких процедур.
Обычно сеанс занимает около четверть часа и проводится в поликлинике без необходимости стационара.
В итоге пациенты наблюдают значительное снижение болей и возвращение объёма движений в проблемной зоне.
child casino
Aw, this was an extremely good post. Taking a few minutes and actual effort to create a top notch article… but what can I say… I procrastinate a whole lot and don’t seem to get nearly anything done.
Питерцы отзовитесь. Вечно то цены конские у дилеров. Пересмотрел ютуб с отзывами — голова пухнет. Короче, реальные производители с совестью — купить кухню от производителя в спб с доставкой. Сделали за три недели. В общем, вся инфа вот здесь — где купить кухню в спб https://zakazat-kuhnyu-gkl.ru Не ведитесь на салоны-прокладки с наценкой в два раза. Сам полгода мучился теперь делюсь.
Ребята кто в Питере живет. Задолбался я уже два месяца мучиться. То сроки изготовления по полгода обещают. Короче, нашел наконец нормальное производство — купить кухню спб с фурнитурой Blum. Приехал замерщик на следующий день после звонка. В общем, жмите чтобы не потерять контакт — где лучше купить кухню в спб https://zakazat-kuhnyu-rty.ru Проверяйте производителя по этому списку. Сам столько нервов потратил теперь делюсь.
Aw, this was a really nice post. Spending some time and actual effort to create a very good article… but what can I say… I hesitate a whole lot and don’t manage to get 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.
child games
Greate post. Keep writing such kind of information on your page. Im really impressed by it.
Aw, this was an exceptionally good post. Taking the time and actual effort to make a great article… but what can I say… I hesitate a lot and never manage to get anything done.
reputable indian online pharmacy: online indian pharmacy – online pharmacy discount code
J’ai essayé pas mal de sites mais rien de concluant. Télécharger un fichier sûr devenait un vrai casse-tête chinois. Après avoir suivi les étapes dans le bon ordre, tout a fonctionné. J’ai finalement trouvé la bonne source et je voulais vous partager tous les détails, vous pouvez consulter les informations à jour ici: 1xbet apk android 1xbet apk android. En deux mots, laissez-moi vous raconter — l’appli tourne super bien sur mon téléphone.
Je n’ai eu aucun problème lors du téléchargement. J’ai comparé plusieurs applis mais celle-ci est la meilleure — ne perdez plus un seul instant avec d’autres sites. Je vous souhaite plein de réussite et de gros gains…
Right now it looks like WordPress is the top 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.
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.
May I just say what a comfort to uncover an individual who actually knows what they are discussing over the internet. You actually know how to bring an issue 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’re not more popular because you certainly have the gift.
Aw, this was an extremely good post. Taking the time and actual effort to produce a great article… but what can I say… I hesitate a whole lot and don’t seem to get nearly anything done.
mostbet letöltés android http://www.mostbet44364.online
At this time it seems like BlogEngine is the best blogging platform available right now. (from what I’ve read) Is that what you’re using on your blog?
Hey there, You have done an excellent job. I’ll definitely digg it and for my part suggest to my friends. I am confident they’ll be benefited from this web site.
Hey there, You have performed an incredible job. I will definitely digg it and in my view recommend to my friends. I’m confident they will be benefited from this website.
другие трип скан официальный сайт
посмотреть в этом разделе tripscan вход
Hi there, You’ve done a great job. I’ll definitely digg it and individually recommend to my friends. I’m sure they’ll be benefited from this web site.
Greate pieces. Keep posting such kind of info on your blog. Im really impressed by your site.
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. Anyways, just wanted to say wonderful blog!
Can I simply just say what a relief to discover a person that actually understands what they’re talking about over the internet. You certainly know how to bring an issue to light and make it important. More and more people have to read this and understand this side of the story. It’s surprising you aren’t more popular because you certainly have the gift.
Currently it seems like Drupal is the best blogging platform out there right now. (from what I’ve read) Is that what you are using on your blog?
Excellent article. Keep writing such kind of information on your page. Im really impressed by your blog.
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. Anyways, just wanted to say wonderful blog!
Greate pieces. Keep posting such kind of info on your site. Im really impressed by your blog.