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.
At this time it appears 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?
Aw, this was an exceptionally nice post. Taking a few minutes and actual effort to create a very good article… but what can I say… I hesitate a lot and never seem to get nearly anything done.
Can I simply say what a relief to uncover someone who truly knows what they’re discussing on the web. You actually understand how to bring an issue to light and make it important. A lot more people must read this and understand this side of your story. I was surprised you’re not more popular because you definitely have the gift.
Hello there, You’ve done a fantastic job. I will certainly digg it and individually suggest to my friends. I’m confident they will be benefited from this web site.
At this time it looks like Drupal is the preferred blogging platform out there right now. (from what I’ve read) Is that what you’re using on your blog?
Currently it appears like Expression Engine is the top blogging platform out there right now. (from what I’ve read) Is that what you’re using on your blog?
Can I simply say what a comfort to find somebody that really understands what they are talking about on the web. You certainly realize how to bring an issue to light and make it important. A lot more people must check this out and understand this side of the story. It’s surprising you are not more popular since you most certainly possess the gift.
Hi there, You have done a great job. I will certainly digg it and individually recommend to my friends. I am confident they will be benefited from this web site.
Читать далее tripskan
Can I just say what a relief to find somebody that actually understands what they are talking about on the net. You certainly realize how to bring a problem to light and make it important. More and more people must check this out and understand this side of your story. It’s surprising you’re not more popular since you most certainly possess the gift.
найти это tripscan официальный сайт
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.
At this time it looks like WordPress is the best blogging platform available right now. (from what I’ve read) Is that what you’re using on your blog?
The flow of ideas throughout this post feels very natural and clearly structured, because each point connects naturally with the next one and helps keep the reader interested from the beginning all the way to the end.
https://dollyolive.co.uk/
Смотреть здесь сайт трипскан
Смотреть здесь tripskan
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?
можно проверить ЗДЕСЬ tripscan зеркало
Перевозка мебели и техники с гарантией сохранности, читайте подробнее здесь <a href=
https://zzb.bz/7ph924
Wow that was odd. I just wrote an extremely long comment but after I clicked submit my comment didn’t appear. Grrrr… well I’m not writing all that over again. Regardless, just wanted to say superb blog!
Hello there, You have done an excellent job. I’ll certainly digg it and individually suggest to my friends. I am sure they’ll be benefited from this site.
Currently it appears like WordPress is the preferred blogging platform available right now. (from what I’ve read) Is that what you’re using on your blog?