[Docs] Improve file formatting (#3409)

Improve the formatting of the documentation.

Author: peter-csala

docs/configure-and-customize-annotations.md

@@ -12,11 +12,10 @@
 2. In the `ConfigureServices` method of `Startup.cs`, enable annotations within in the Swagger config block:
 
     ```csharp
-    services.AddSwaggerGen(c =>
+    services.AddSwaggerGen(options =>
     {
-       ...
-
-       c.EnableAnnotations();
+        //...
+        options.EnableAnnotations();
     });
     ```
 
@@ -26,7 +25,6 @@ Once annotations have been enabled, you can enrich the generated Operation metad
 
 ```csharp
 [HttpPost]
-
 [SwaggerOperation(
     Summary = "Creates a new product",
     Description = "Requires admin privileges",
@@ -38,7 +36,7 @@ public IActionResult Create([FromBody]Product product)
 
 ## Enrich Response Metadata
 
-ASP.NET Core provides the `ProducesResponseTypeAttribute` for listing the different responses that can be returned by an action. These attributes can be combined with XML comments, as described [above](#include-descriptions-from-xml-comments), to include human friendly descriptions with each response in the generated Swagger. If you'd prefer to do all of this with a single attribute, and avoid the use of XML comments, you can use `SwaggerResponseAttribute`s instead:
+ASP.NET Core provides the `ProducesResponseTypeAttribute` for listing the different responses that can be returned by an action. These attributes can be combined with XML comments, as described [here](configure-and-customize-swaggergen.md#include-descriptions-from-xml-comments), to include human friendly descriptions with each response in the generated Swagger. If you'd prefer to do all of this with a single attribute, and avoid the use of XML comments, you can use `SwaggerResponseAttribute`s instead:
 
 ```csharp
 [HttpPost]
@@ -86,21 +84,24 @@ public class Product
 }
 ```
 
-_NOTE: In Swagger / OpenAPI, serialized objects AND contained properties are represented as `Schema` instances, hence why this annotation can be applied to both classes and properties. Also worth noting, "required" properties are specified as an array of property names on the top-level schema as opposed to a flag on each individual property._
+> [!NOTE]
+> In Swagger / OpenAPI, serialized objects AND contained properties are represented as `Schema` instances, hence why this annotation can be applied to both classes and properties. Also worth noting, "required" properties are specified as an array of property names on the top-level schema as opposed to a flag on each individual property.
 
 ## Apply Schema Filters to Specific Types
 
-The `SwaggerGen` package provides several extension points, including Schema Filters ([described here](#extend-generator-with-operation-schema--document-filter)) for customizing ALL generated Schemas. However, there may be cases where it's preferable to apply a filter to a specific Schema. For example, if you'd like to include an example for a specific type in your API. This can be done by decorating the type with a `SwaggerSchemaFilterAttribute`:
+The `SwaggerGen` package provides several extension points, including Schema Filters (described [here](configure-and-customize-swaggergen.md#extend-generator-with-operation-schema--document-filter)) for customizing **all** generated Schemas. However, there may be cases where it's preferable to apply a filter to a specific Schema. For example, if you'd like to include an example for a specific type in your API. This can be done by decorating the type with a `SwaggerSchemaFilterAttribute`:
 
+📝 `Product.cs`
 ```csharp
-// Product.cs
 [SwaggerSchemaFilter(typeof(ProductSchemaFilter))]
 public class Product
 {
-    ...
+    //...
 }
+```
 
-// ProductSchemaFilter.cs
+📝 `ProductSchemaFilter.cs`
+```csharp
 public class ProductSchemaFilter : ISchemaFilter
 {
     public void Apply(OpenApiSchema schema, SchemaFilterContext context)
@@ -122,25 +123,27 @@ By default, the Swagger generator will tag all operations with the controller na
 [SwaggerTag("Create, read, update and delete Products")]
 public class ProductsController
 {
-    ...
+    //...
 }
 ```
 
-_NOTE: This will add the above description specifically to the tag named "Products". Therefore, you should avoid using this attribute if you're tagging Operations with something other than controller name - e.g. if you're customizing the tagging behavior with `TagActionsBy`._
+> [!NOTE] 
+> This will add the above description specifically to the tag named "Products". Therefore, you should avoid using this attribute if you're tagging Operations with something other than controller name - e.g. if you're customizing the tagging behavior with `TagActionsBy`.
 
 ## List Known Subtypes for Inheritance and Polymorphism
 
-If you want to use Swashbuckle's [inheritance and/or polymorphism behavior](#inheritance-and-polymorphism), you can use annotations to _explicitly_ indicate the "known" subtypes for a given base type. This will override the default selector function, which selects _all_ subtypes in the same assembly as the base type, and therefore needs to be explicitly enabled when you enable Annotations:
+If you want to use Swashbuckle's [inheritance and/or polymorphism behavior](configure-and-customize-swaggergen.md#inheritance-and-polymorphism), you can use annotations to _explicitly_ indicate the "known" subtypes for a given base type. This will override the default selector function, which selects _all_ subtypes in the same assembly as the base type, and therefore needs to be explicitly enabled when you enable Annotations:
 
+📝 `Startup.cs`
 ```csharp
-// Startup.cs
-services.AddSwaggerGen(c =>
+services.AddSwaggerGen(options =>
 {
-    c.EnableAnnotations(enableAnnotationsForInheritance: true, enableAnnotationsForPolymorphism: true);
+    options.EnableAnnotations(enableAnnotationsForInheritance: true, enableAnnotationsForPolymorphism: true);
 });
+```
 
-// Shape.cs
-
+📝 `Shape.cs`
+```csharp
 // .NET 7 or later
 [JsonDerivedType(typeof(Rectangle))]
 [JsonDerivedType(typeof(Circle))]
@@ -160,16 +163,16 @@ public abstract class Shape
 
 If you're using annotations to _explicitly_ indicate the "known" subtypes for a polymorphic base type, you can combine the `JsonPolymorphicAttribute` with the `JsonDerivedTypeAttribute` to provide additional metadata about the "discriminator" property, which will then be incorporated into the generated schema definition:
 
-
+📝 `Startup.cs`
 ```csharp
-// Startup.cs
-services.AddSwaggerGen(c =>
+services.AddSwaggerGen(options =>
 {
-    c.EnableAnnotations(enableAnnotationsForInheritance: true, enableAnnotationsForPolymorphism: true);
+    options.EnableAnnotations(enableAnnotationsForInheritance: true, enableAnnotationsForPolymorphism: true);
 });
+```
 
-// Shape.cs
-
+📝 `Shape.cs`
+```csharp
 // .NET 7 or later
 [JsonPolymorphic(TypeDiscriminatorPropertyName = "shapeType")]
 [JsonDerivedType(typeof(Rectangle), "rectangle")]
@@ -200,7 +203,7 @@ public enum ShapeType
 
 This indicates that the corresponding payload will have a "shapeType" property to discriminate between subtypes, and that property will have a value of "rectangle" if the payload represents a `Rectangle` type and a value of "circle" if it represents a `Circle` type. This detail will be described in the generated schema definition as follows:
 
-```
+```yaml
 schema: {
   oneOf: [
     {

docs/configure-and-customize-cli.md

@@ -2,11 +2,12 @@
 
 ## Retrieve Swagger Directly from a Startup Assembly 
 
-Once your application has been setup with Swashbuckle (see [Getting Started](#getting-started)), you can use the Swashbuckle CLI tool to retrieve Swagger / OpenAPI JSON directly from your application's startup assembly, and write it to file. This can be useful if you want to incorporate Swagger generation into a CI/CD process, or if you want to serve it from static file at run-time.
+Once your application has been setup with Swashbuckle (see [Getting Started](../README.md#getting-started)), you can use the Swashbuckle CLI tool to retrieve Swagger / OpenAPI JSON directly from your application's startup assembly, and write it to file. This can be useful if you want to incorporate Swagger generation into a CI/CD process, or if you want to serve it from static file at run-time.
 
 It's packaged as a [.NET Tool](https://learn.microsoft.com/dotnet/core/tools/global-tools) that can be installed and used via the dotnet SDK.
 
-> :warning: The tool needs to load your Startup DLL and its dependencies at runtime. Therefore, you should use a version of the `dotnet` SDK that is compatible with your application. For example, if your app targets `net8.0`, then you should use version 8.0.xxx of the SDK to run the CLI tool. If it targets `net9.0`, then you should use version 9.0.xxx of the SDK and so on.
+> [!WARNING] 
+> The tool needs to load your Startup DLL and its dependencies at runtime. Therefore, you should use a version of the `dotnet` SDK that is compatible with your application. For example, if your app targets `net8.0`, then you should use version 8.0.xxx of the SDK to run the CLI tool. If it targets `net9.0`, then you should use version 9.0.xxx of the SDK and so on.
 
 ### Using the tool with the .NET SDK
 
@@ -28,10 +29,10 @@ It's packaged as a [.NET Tool](https://learn.microsoft.com/dotnet/core/tools/glo
     swagger tofile --output [output] [startupassembly] [swaggerdoc]
     ```
 
-    Where ...
-    * [output] is the relative path where the Swagger JSON will be output to
-    * [startupassembly] is the relative path to your application's startup assembly
-    * [swaggerdoc] is the name of the swagger document you want to retrieve, as configured in your startup class
+    Placeholders and their meaning:
+    * `[output]`: the relative path where the Swagger JSON will be output to
+    * `[startupassembly]`: the relative path to your application's startup assembly
+    * `[swaggerdoc]`: the name of the swagger document you want to retrieve, as configured in your startup class
 
 ### Using the tool with the .NET 6.0 SDK or later
 
@@ -59,10 +60,10 @@ It's packaged as a [.NET Tool](https://learn.microsoft.com/dotnet/core/tools/glo
     dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc]
     ```
 
-    Where ...
-    * [output] is the relative path where the Swagger JSON will be output to
-    * [startupassembly] is the relative path to your application's startup assembly
-    * [swaggerdoc] is the name of the swagger document you want to retrieve, as configured in your startup class
+    Placeholders and their meaning:
+    * `[output]`: the relative path where the Swagger JSON will be output to
+    * `[startupassembly]`: the relative path to your application's startup assembly
+    * `[swaggerdoc]`: the name of the swagger document you want to retrieve, as configured in your startup class
 
 ## Use the CLI Tool with a Custom Host Configuration
 

docs/configure-and-customize-redoc.md

@@ -2,86 +2,88 @@
 
 ## Change Relative Path to the UI
 
-By default, the Redoc UI will be exposed at "/api-docs". If necessary, you can alter this when enabling the Redoc middleware:
+By default, the Redoc UI will be exposed at `"/api-docs"`. If necessary, you can alter this when enabling the Redoc middleware:
 
 ```csharp
-app.UseReDoc(c =>
+app.UseReDoc(options =>
 {
-    c.RoutePrefix = "docs"
-    ...
-}
+    options.RoutePrefix = "docs"
+    //...
+});
 ```
 
 ## Change Document Title
 
 By default, the Redoc UI will have a generic document title. You can alter this when enabling the Redoc middleware:
 
 ```csharp
-app.UseReDoc(c =>
+app.UseReDoc(options =>
 {
-    c.DocumentTitle = "My API Docs";
-    ...
-}
+    options.DocumentTitle = "My API Docs";
+    //...
+});
 ```
 
 ## Apply Redoc Parameters
 
-Redoc ships with its own set of configuration parameters, all described here https://github.com/Rebilly/redoc/blob/main/README.md#redoc-options-object. In Swashbuckle, most of these are surfaced through the Redoc middleware options:
+Redoc ships with its own set of configuration parameters, all described [here](https://github.com/Rebilly/redoc/blob/main/README.md#redoc-options-object). In Swashbuckle, most of these are surfaced through the Redoc middleware options:
 
 ```csharp
-app.UseReDoc(c =>
+app.UseReDoc(options =>
 {
-    c.SpecUrl("/v1/swagger.json");
-    c.EnableUntrustedSpec();
-    c.ScrollYOffset(10);
-    c.HideHostname();
-    c.HideDownloadButton();
-    c.ExpandResponses("200,201");
-    c.RequiredPropsFirst();
-    c.NoAutoAuth();
-    c.PathInMiddlePanel();
-    c.HideLoading();
-    c.NativeScrollbars();
-    c.DisableSearch();
-    c.OnlyRequiredInSamples();
-    c.SortPropsAlphabetically();
+    options.SpecUrl("/v1/swagger.json");
+    options.EnableUntrustedSpec();
+    options.ScrollYOffset(10);
+    options.HideHostname();
+    options.HideDownloadButton();
+    options.ExpandResponses("200,201");
+    options.RequiredPropsFirst();
+    options.NoAutoAuth();
+    options.PathInMiddlePanel();
+    options.HideLoading();
+    options.NativeScrollbars();
+    options.DisableSearch();
+    options.OnlyRequiredInSamples();
+    options.SortPropsAlphabetically();
 });
 ```
 
-_Using `c.SpecUrl("/v1/swagger.json")` multiple times within the same `UseReDoc(...)` will not add multiple urls._
+> [!NOTE]
+> Using `options.SpecUrl("/v1/swagger.json")` multiple times within the same `UseReDoc(...)` will not add multiple URL.
 
 ## Inject Custom CSS
 
 To tweak the look and feel, you can inject additional CSS stylesheets by adding them to your `wwwroot` folder and specifying the relative paths in the middleware options:
 
 ```csharp
-app.UseReDoc(c =>
+app.UseReDoc(options =>
 {
-    ...
-    c.InjectStylesheet("/redoc/custom.css");
-}
+    //...
+    options.InjectStylesheet("/redoc/custom.css");
+});
 ```
 
-It is also possible to modify the theme by using the `AdditionalItems` property, see https://github.com/Rebilly/redoc/blob/main/README.md#redoc-options-object for more information.
+It is also possible to modify the theme by using the `AdditionalItems` property, more information can be found [here](https://github.com/Rebilly/redoc/blob/main/README.md#redoc-options-object).
 
 ```csharp
-app.UseReDoc(c =>
+app.UseReDoc(options =>
 {
-    ...
-    c.ConfigObject.AdditionalItems = ...
-}
+    //...
+    options.ConfigObject.AdditionalItems = ...
+});
 ```
 
 ## Customize index.html
 
-To customize the UI beyond the basic options listed above, you can provide your own version of the Redoc index.html page:
+To customize the UI beyond the basic options listed above, you can provide your own version of the Redoc `index.html` page:
 
 ```csharp
-app.UseReDoc(c =>
+app.UseReDoc(options =>
 {
-    c.IndexStream = () => GetType().Assembly
+    options.IndexStream = () => GetType().Assembly
         .GetManifestResourceStream("CustomIndex.ReDoc.index.html"); // requires file to be added as an embedded resource
 });
 ```
 
-_To get started, you should base your custom index.html on the [default version](src/Swashbuckle.AspNetCore.ReDoc/index.html)_
+> [!TIP]
+> To get started, you should base your custom `index.html` on the [default version](../src/Swashbuckle.AspNetCore.ReDoc/index.html).