{"id":9751,"date":"2021-07-17T00:35:25","date_gmt":"2021-07-17T05:35:25","guid":{"rendered":"https:\/\/krisbunda.com\/blog\/?p=9751"},"modified":"2023-04-19T22:44:24","modified_gmt":"2023-04-20T03:44:24","slug":"annotate-net-classes-for-better-swagger-api-endpoint-documentation","status":"publish","type":"post","link":"https:\/\/krisbunda.com\/blog\/2021\/07\/17\/annotate-net-classes-for-better-swagger-api-endpoint-documentation\/","title":{"rendered":"Annotate .NET Classes for Better Swagger API Endpoint Documentation"},"content":{"rendered":"\n<p>Swagger is an API endpoint documentation tool, and it&#8217;s great for showing a developer or system integrator how an API works. It&#8217;s proven so popular and useful that these days I think Swagger (Swashbuckle) is now installed by default in the starter templates when you create a new ASP.NET Core or .NET 5 app app in Visual Studio. <\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Helpful API Documentation<\/h2>\n\n\n\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"1200\" height=\"1286\" src=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-1200x1286.png\" alt=\"Typical swagger API endpoint documentation list page\" class=\"wp-image-9753\" srcset=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-1200x1286.png 1200w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-600x643.png 600w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-140x150.png 140w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-1433x1536.png 1433w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-1911x2048.png 1911w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0.png 1941w\" sizes=\"auto, (max-width: 1200px) 100vw, 1200px\" \/><figcaption>swagger swashbuckle annotation for better API endpoint documentation 0<\/figcaption><\/figure>\n\n\n<style>.wp-block-kadence-advancedheading.kt-adv-heading_ef5705-c1, .wp-block-kadence-advancedheading.kt-adv-heading_ef5705-c1[data-kb-block=\"kb-adv-heading_ef5705-c1\"]{font-style:normal;}.wp-block-kadence-advancedheading.kt-adv-heading_ef5705-c1 mark.kt-highlight, .wp-block-kadence-advancedheading.kt-adv-heading_ef5705-c1[data-kb-block=\"kb-adv-heading_ef5705-c1\"] mark.kt-highlight{font-style:normal;color:#f76a0c;-webkit-box-decoration-break:clone;box-decoration-break:clone;padding-top:0px;padding-right:0px;padding-bottom:0px;padding-left:0px;}.wp-block-kadence-advancedheading.kt-adv-heading_ef5705-c1 img.kb-inline-image, .wp-block-kadence-advancedheading.kt-adv-heading_ef5705-c1[data-kb-block=\"kb-adv-heading_ef5705-c1\"] img.kb-inline-image{width:150px;vertical-align:baseline;}<\/style>\n<h2 class=\"kt-adv-heading_ef5705-c1 wp-block-kadence-advancedheading\" data-kb-block=\"kb-adv-heading_ef5705-c1\">For MOST Swagger Customization: Just Use Microsoft Docs.<\/h2>\n\n\n\n<p>The people behind Microsoft Docs, who I think do a great job, <a aria-label=\"already made some great instructionals (opens in a new tab)\" href=\"https:\/\/docs.microsoft.com\/en-us\/aspnet\/core\/tutorials\/getting-started-with-swashbuckle?view=aspnetcore-5.0&amp;tabs=visual-studio\" target=\"_blank\" rel=\"noreferrer noopener\" class=\"ek-link\">already made some great instructionals<\/a> and <a aria-label=\" (opens in a new tab)\" href=\"https:\/\/docs.microsoft.com\/en-us\/learn\/modules\/improve-api-developer-experience-with-swagger\/4-visualize-and-interact-with-api-resources\" target=\"_blank\" rel=\"noreferrer noopener\" class=\"ek-link\">a nice tutorial on how to do most of what I&#8217;m about to show you<\/a>. Although I&#8217;m slightly annoyed, since I was able to find these resources so easily today, yet it took much longer to piecemeal this annotation process together previously (from the darkest corners of Stack Overflow and .NET chat boards&#8230;) but that is the way of the Google-Fu. <\/p>\n\n\n\n<figure class=\"wp-block-pullquote alignfull has-background has-kb-palette-3-background-color is-style-solid-color\"><blockquote class=\"has-text-color\" style=\"color:#000000\"><p>For those answers you seek most desperately, and in the hour you most desperately seek them, they shall elude your search results&#8230;<\/p><cite>\u2014 Google, probably<\/cite><\/blockquote><\/figure>\n\n\n\n<p>Here are some images and examples of using markup for more elaborate and verbose endpoint documentation&#8211;you can find all this info on MS Docs and tutorials links in the paragraph above.<strong> After the images, I&#8217;ll get into what I haven&#8217;t seen on MS Docs nor from many other places<\/strong>: How to annotate models to show specific samples for each attribute of  your data structure on your Swagger page.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Notice what&#8217;s written in the markup image and then connect it to where it appears in the Swagger documentation images. <\/h4>\n\n\n\n<p>Remember, the 3 forward slashes <code>{ \/\/\/ }<\/code> are important, as well as proper element names and syntax <code>{ &lt;open>and&lt;\/close> correct tag names }<\/code>. <\/p>\n\n\n\n<p>(The below screenshot isn&#8217;t the shining-est example since now it&#8217;s apparent I have 2 sets of <code>&lt;remarks><\/code> tags for the <code>GetProduct<\/code> action, and didn&#8217;t define descriptions for parameters [do that between the <code>&lt;param><\/code> tags, like so: <code>&lt;param name=\"id\"><em>Unique ID of the Product.<\/em>&lt;\/param><\/code>], but you get the idea).<\/p>\n\n\n\n<figure class=\"wp-block-gallery columns-1 is-cropped wp-block-gallery-2 is-layout-flex wp-block-gallery-is-layout-flex\"><ul class=\"blocks-gallery-grid\"><li class=\"blocks-gallery-item\"><figure><a href=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-2.png\"><img loading=\"lazy\" decoding=\"async\" width=\"1200\" height=\"1314\" src=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-2-1200x1314.png\" alt=\"Adding helpful documentation to a .NET app controller to display on a Swagger API endpoints page.\" data-id=\"9755\" data-full-url=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-2.png\" data-link=\"https:\/\/krisbunda.com\/blog\/?attachment_id=9755\" class=\"wp-image-9755\" srcset=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-2-1200x1314.png 1200w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-2-600x657.png 600w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-2-137x150.png 137w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-2-1402x1536.png 1402w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-2-1870x2048.png 1870w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-2.png 1899w\" sizes=\"auto, (max-width: 1200px) 100vw, 1200px\" \/><\/a><figcaption class=\"blocks-gallery-item__caption\">swagger swashbuckle annotation for better API endpoint documentation 2<\/figcaption><\/figure><\/li><li class=\"blocks-gallery-item\"><figure><a href=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0.png\"><img loading=\"lazy\" decoding=\"async\" width=\"1200\" height=\"1286\" src=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-1200x1286.png\" alt=\"Typical swagger API endpoint documentation list page\" data-id=\"9753\" data-full-url=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0.png\" data-link=\"https:\/\/krisbunda.com\/blog\/?attachment_id=9753\" class=\"wp-image-9753\" srcset=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-1200x1286.png 1200w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-600x643.png 600w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-140x150.png 140w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-1433x1536.png 1433w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0-1911x2048.png 1911w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-0.png 1941w\" sizes=\"auto, (max-width: 1200px) 100vw, 1200px\" \/><\/a><figcaption class=\"blocks-gallery-item__caption\">swagger swashbuckle annotation for better API endpoint documentation 0<\/figcaption><\/figure><\/li><li class=\"blocks-gallery-item\"><figure><a href=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-1.png\"><img loading=\"lazy\" decoding=\"async\" width=\"1200\" height=\"1286\" src=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-1-1200x1286.png\" alt=\"Swagger API endpoint Request Body helpful example documentation\" data-id=\"9754\" data-full-url=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-1.png\" data-link=\"https:\/\/krisbunda.com\/blog\/?attachment_id=9754\" class=\"wp-image-9754\" srcset=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-1-1200x1286.png 1200w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-1-600x643.png 600w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-1-140x150.png 140w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-1-1433x1536.png 1433w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-1-1911x2048.png 1911w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-1.png 1941w\" sizes=\"auto, (max-width: 1200px) 100vw, 1200px\" \/><\/a><figcaption class=\"blocks-gallery-item__caption\">swagger swashbuckle annotation for better API endpoint documentation 1<\/figcaption><\/figure><\/li><\/ul><figcaption class=\"blocks-gallery-caption\">Look at the controller markup and find where those items are then shown in the Swagger documentation.<\/figcaption><\/figure>\n\n\n\n<h2 class=\"wp-block-heading\">Some Swagger (Swashbuckle) pages are documented better than others. <\/h2>\n\n\n\n<p>A lot of API endpoints are named intuitively, but some could benefit from a little more documentation. The &#8220;Example Value&#8221; of a Request Body is very helpful for showing the data structure, but typically the <a aria-label=\"parameter examples are shown simply as data types (opens in a new tab)\" href=\"https:\/\/swagger.io\/docs\/specification\/data-models\/data-types\/\" target=\"_blank\" rel=\"noreferrer noopener\" class=\"ek-link\">parameter examples are shown simply as data types<\/a> (i.e. <code>string<\/code>, <code>integer<\/code>, <code>boolean<\/code>). <\/p>\n\n\n\n<p>I prefer the Request Body &gt; Example Value to show the key:value pairs with <em>examples <\/em>for the values&#8211;not just data types. If you feel the same, that&#8217;s the reason for this blog&#8211;it seems like how to do this is not covered much in the documentation I&#8217;ve read.<\/p>\n\n\n\n<figure class=\"wp-block-gallery columns-1 wp-block-gallery-3 is-layout-flex wp-block-gallery-is-layout-flex\"><ul class=\"blocks-gallery-grid\"><li class=\"blocks-gallery-item\"><figure><a href=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-7.png\"><img loading=\"lazy\" decoding=\"async\" width=\"450\" height=\"501\" src=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-7.png\" alt=\"Swagger Request Body: DEFAULT Example Value Schema\" data-id=\"9759\" data-full-url=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-7.png\" data-link=\"https:\/\/krisbunda.com\/blog\/?attachment_id=9759\" class=\"wp-image-9759\" srcset=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-7.png 450w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-7-135x150.png 135w\" sizes=\"auto, (max-width: 450px) 100vw, 450px\" \/><\/a><figcaption class=\"blocks-gallery-item__caption\">Swagger Response Body default Example Value Schema<\/figcaption><\/figure><\/li><li class=\"blocks-gallery-item\"><figure><a href=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-8.png\"><img loading=\"lazy\" decoding=\"async\" width=\"600\" height=\"326\" src=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-8-600x326.png\" alt=\"Swagger Response Body: CUSTOM and helpful Example Value Schema\" data-id=\"9760\" data-full-url=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-8.png\" data-link=\"https:\/\/krisbunda.com\/blog\/?attachment_id=9760\" class=\"wp-image-9760\" srcset=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-8-600x326.png 600w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-8-150x81.png 150w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-8.png 1028w\" sizes=\"auto, (max-width: 600px) 100vw, 600px\" \/><\/a><figcaption class=\"blocks-gallery-item__caption\">Swagger Response Body more helpful Example Value Schema<\/figcaption><\/figure><\/li><\/ul><figcaption class=\"blocks-gallery-caption\">Compare the default Request Body example (first) to the custom &amp; more-helpful version.<\/figcaption><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">But how do you make the documentation more specific and helpful? <\/h3>\n\n\n\n<p>By annotating the Model(s) in a notation format that Swagger will understand. This means you add 3 forward slashes <code>{ \/\/\/ }<\/code> before writing your <code>&lt;example&gt;<\/code> element, and do it above each attribute line in your entity model class as shown below. <\/p>\n\n\n\n<p>Notice use of only 2 slashes <code>{ \/\/ }<\/code> is parsed as a regular code comment and Swagger will ignore these <code>&lt;example><\/code>&#8216;s.<\/p>\n\n\n\n<figure class=\"wp-block-gallery columns-1 is-cropped wp-block-gallery-4 is-layout-flex wp-block-gallery-is-layout-flex\"><ul class=\"blocks-gallery-grid\"><li class=\"blocks-gallery-item\"><figure><a href=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-4-1200x1303.png\"><img loading=\"lazy\" decoding=\"async\" width=\"1200\" height=\"1303\" src=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-4-1200x1303.png\" alt=\"\" data-id=\"9771\" class=\"wp-image-9771\" srcset=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-4-1200x1303.png 1200w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-4-600x652.png 600w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-4-138x150.png 138w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-4-1414x1536.png 1414w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-4.png 1882w\" sizes=\"auto, (max-width: 1200px) 100vw, 1200px\" \/><\/a><\/figure><\/li><li class=\"blocks-gallery-item\"><figure><a href=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-5.png\"><img loading=\"lazy\" decoding=\"async\" width=\"1200\" height=\"1429\" src=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-5-1200x1429.png\" alt=\"\" data-id=\"9772\" data-full-url=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-5.png\" data-link=\"https:\/\/krisbunda.com\/blog\/?attachment_id=9772\" class=\"wp-image-9772\" srcset=\"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-5-1200x1429.png 1200w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-5-600x714.png 600w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-5-126x150.png 126w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-5-1290x1536.png 1290w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-5-1720x2048.png 1720w, https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/swagger-swashbuckle-annotation-for-better-API-endpoint-documentation-5.png 1894w\" sizes=\"auto, (max-width: 1200px) 100vw, 1200px\" \/><\/a><\/figure><\/li><\/ul><\/figure>\n\n\n\n<p>Here&#8217;s the code of the sample model class shown above: <\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre class=\"CodeMirror\" data-setting=\"{&quot;showPanel&quot;:true,&quot;languageLabel&quot;:&quot;language&quot;,&quot;fullScreenButton&quot;:true,&quot;copyButton&quot;:true,&quot;mode&quot;:&quot;clike&quot;,&quot;mime&quot;:&quot;text\/x-csharp&quot;,&quot;theme&quot;:&quot;dracula&quot;,&quot;lineNumbers&quot;:true,&quot;styleActiveLine&quot;:true,&quot;lineWrapping&quot;:true,&quot;readOnly&quot;:true,&quot;fileName&quot;:&quot;&quot;,&quot;language&quot;:&quot;C#&quot;,&quot;maxHeight&quot;:&quot;400px&quot;,&quot;modeName&quot;:&quot;csharp&quot;}\">using MongoDB.Bson;\nusing MongoDB.Bson.Serialization.Attributes;\n\nnamespace Catalog.API.Entities\n{\n\tpublic class Product\n\t{\n      \/\/placement matters, if you put the &lt;example&gt; below the other annoations, like\n      \/\/below the [BsonId] tag, then the &lt;example&gt; notation probably won't work.\n\t\t\/\/\/ &lt;example&gt;6073ca0bd932aa3291eb524f&lt;\/example&gt;\n\t\t[BsonId]\n\t\t[BsonRepresentation(BsonType.ObjectId)]\n\t\tpublic string Id { get; set; }\n\n\t\t\/\/\/ &lt;example&gt;Surface Go&lt;\/example&gt;\n\t\tpublic string Name { get; set; }\n\n\t\t\/\/\/ &lt;example&gt;Tablets&lt;\/example&gt;\n\t\tpublic string Category { get; set; }\n\n\t\t\/\/\/ &lt;example&gt;10.5in touchscreen tablet with keyboard and stylus&lt;\/example&gt;\n\t\tpublic string Summary { get; set; }\n\n\t\t\/\/\/ &lt;example&gt;Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ut, tenetur natus doloremque laborum quos iste ipsum rerum obcaecati impedit odit illo dolorum ab tempora nihil dicta earum fugiat. Temporibus, voluptatibus. Lorem ipsum dolor sit amet, consectetur adipisicing elit.&lt;\/example&gt;\n\t\tpublic string Description { get; set; }\n\n\t\t\/\/\/ &lt;example&gt;product-1.png&lt;\/example&gt;\n\t\tpublic string ImageFile { get; set; }\n\n\t\t\/\/\/ &lt;example&gt;490.99&lt;\/example&gt;\n\t\tpublic decimal Price { get; set; }\n\t}\n}<\/pre><\/div>\n\n\n\n<p>And Here&#8217;s the resulting JSON that Swagger presents as the Example Value:<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre class=\"CodeMirror\" data-setting=\"{&quot;showPanel&quot;:true,&quot;languageLabel&quot;:&quot;language&quot;,&quot;fullScreenButton&quot;:true,&quot;copyButton&quot;:true,&quot;mode&quot;:&quot;javascript&quot;,&quot;mime&quot;:&quot;application\/json&quot;,&quot;theme&quot;:&quot;dracula&quot;,&quot;lineNumbers&quot;:true,&quot;styleActiveLine&quot;:true,&quot;lineWrapping&quot;:true,&quot;readOnly&quot;:true,&quot;fileName&quot;:&quot;&quot;,&quot;language&quot;:&quot;JSON&quot;,&quot;maxHeight&quot;:&quot;400px&quot;,&quot;modeName&quot;:&quot;json&quot;}\">[\n  {\n    &quot;id&quot;: &quot;6073ca0bd932aa3291eb524f&quot;,\n    &quot;name&quot;: &quot;Surface Go&quot;,\n    &quot;category&quot;: &quot;Tablets&quot;,\n    &quot;summary&quot;: &quot;10.5in touchscreen tablet with keyboard and stylus&quot;,\n    &quot;description&quot;: &quot;Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ut, tenetur natus doloremque laborum quos iste ipsum rerum obcaecati impedit odit illo dolorum ab tempora nihil dicta earum fugiat. Temporibus, voluptatibus. Lorem ipsum dolor sit amet, consectetur adipisicing elit.&quot;,\n    &quot;imageFile&quot;: &quot;product-1.png&quot;,\n    &quot;price&quot;: 490.99\n  }\n]<\/pre><\/div>\n\n\n\n<p>If you&#8217;re having trouble getting your examples to show up on your Swagger page, make sure you did all the other stuff from the Microsoft Docs links above, including registering XML comments in your app&#8217;s <code>Startup.cs<\/code> class.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>How to annotate .NET classes so Swagger (Swashbuckle) API endpoint documentation is more helpful, especially adding Examples to the Request Body instead of the default: data types. <\/p>\n","protected":false},"author":1,"featured_media":9761,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_editorskit_title_hidden":false,"_editorskit_reading_time":4,"_editorskit_is_block_options_detached":false,"_editorskit_block_options_position":"{}","inline_featured_image":false,"kt_blocks_editor_width":"","_kad_blocks_custom_css":"","_kad_blocks_head_custom_js":"","_kad_blocks_body_custom_js":"","_kad_blocks_footer_custom_js":"","jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[4],"tags":[794,793,795,797,798,796],"class_list":["post-9751","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-designer","tag-net","tag-api","tag-c","tag-documentation","tag-endpoints","tag-swagger"],"aioseo_notices":[],"jetpack_publicize_connections":[],"taxonomy_info":{"category":[{"value":4,"label":"Designer"}],"post_tag":[{"value":794,"label":".NET"},{"value":793,"label":"API"},{"value":795,"label":"C#"},{"value":797,"label":"Documentation"},{"value":798,"label":"endpoints"},{"value":796,"label":"Swagger"}]},"featured_image_src_large":["https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/cover-1200x676.jpg",1200,676,true],"author_info":{"display_name":"Kris Bunda","author_link":"https:\/\/krisbunda.com\/blog\/author\/kris-bunda\/"},"comment_info":1,"category_info":[{"term_id":4,"name":"Designer","slug":"designer","term_group":0,"term_taxonomy_id":4,"taxonomy":"category","description":"Posts focusing on web, graphic, CAD, and other design.","parent":0,"count":91,"filter":"raw","cat_ID":4,"category_count":91,"category_description":"Posts focusing on web, graphic, CAD, and other design.","cat_name":"Designer","category_nicename":"designer","category_parent":0}],"tag_info":[{"term_id":794,"name":".NET","slug":"net","term_group":0,"term_taxonomy_id":798,"taxonomy":"post_tag","description":"","parent":0,"count":1,"filter":"raw"},{"term_id":793,"name":"API","slug":"api","term_group":0,"term_taxonomy_id":797,"taxonomy":"post_tag","description":"","parent":0,"count":1,"filter":"raw"},{"term_id":795,"name":"C#","slug":"c","term_group":0,"term_taxonomy_id":799,"taxonomy":"post_tag","description":"","parent":0,"count":0,"filter":"raw"},{"term_id":797,"name":"Documentation","slug":"documentation","term_group":0,"term_taxonomy_id":801,"taxonomy":"post_tag","description":"","parent":0,"count":1,"filter":"raw"},{"term_id":798,"name":"endpoints","slug":"endpoints","term_group":0,"term_taxonomy_id":802,"taxonomy":"post_tag","description":"","parent":0,"count":1,"filter":"raw"},{"term_id":796,"name":"Swagger","slug":"swagger","term_group":0,"term_taxonomy_id":800,"taxonomy":"post_tag","description":"","parent":0,"count":0,"filter":"raw"}],"jetpack_featured_media_url":"https:\/\/krisbunda.com\/blog\/wp-content\/uploads\/2021\/07\/cover.jpg","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p1NcZe-2xh","amp_enabled":true,"_links":{"self":[{"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/posts\/9751","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/comments?post=9751"}],"version-history":[{"count":5,"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/posts\/9751\/revisions"}],"predecessor-version":[{"id":9797,"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/posts\/9751\/revisions\/9797"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/media\/9761"}],"wp:attachment":[{"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/media?parent=9751"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/categories?post=9751"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/krisbunda.com\/blog\/wp-json\/wp\/v2\/tags?post=9751"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}