Document everything

Modules/ApiBrowsing/ApiBrowser.cs

@@ -1,42 +1,24 @@
 using GenHTTP.Modules.ApiBrowsing.Common;
-using GenHTTP.Modules.Layouting.Provider;
 
 namespace GenHTTP.Modules.ApiBrowsing;
 
+/// <summary>
+/// Provides graphical, JavaScript based web applications that render an Open API
+/// definition so that the API can be explored by users.
+/// </summary>
 public static class ApiBrowser
 {
 
-    #region Factories
-
+    /// <summary>
+    /// Creates a handler that will provide a Swagger UI app.
+    /// </summary>
+    /// <returns>The newly created handler</returns>
     public static BrowserHandlerBuilder SwaggerUI() => new("Swagger", "Swagger UI");
 
+    /// <summary>
+    /// Creates a handler that will provide a Redoc app.
+    /// </summary>
+    /// <returns>The newly created handler</returns>
     public static BrowserHandlerBuilder Redoc() => new("Redoc", "Redoc");
 
-    #endregion
-
-    #region Layout extensions
-
-    public static LayoutBuilder AddSwaggerUI(this LayoutBuilder layout, string segment = "swagger", string? url = null, string? title = null)
-        => AddBrowser(layout, SwaggerUI(), segment, url, title);
-
-    public static LayoutBuilder AddRedoc(this LayoutBuilder layout, string segment = "redoc", string? url = null, string? title = null)
-        => AddBrowser(layout, Redoc(), segment, url, title);
-
-    private static LayoutBuilder AddBrowser(this LayoutBuilder layout, BrowserHandlerBuilder builder, string segment, string? url, string? title)
-    {
-        if (url != null)
-        {
-            builder.Url(url);
-        }
-
-        if (title != null)
-        {
-            builder.Title(title);
-        }
-
-        return layout.Add(segment, builder);
-    }
-
-    #endregion
-
 }

Modules/ApiBrowsing/Common/BrowserHandlerBuilder.cs

@@ -10,12 +10,21 @@ public class BrowserHandlerBuilder(string resourceRoot, string title) : IHandler
 
     private string _Title = title;
 
+    /// <summary>
+    /// Sets the URL of the Open API definition to be consumed (defaults to "../openapi.json").
+    /// Should be relative to avoid issues with CORS etc.
+    /// </summary>
+    /// <param name="url">The URL the application will fetch the Open API definition from</param>
     public BrowserHandlerBuilder Url(string url)
     {
         _Url = url;
         return this;
     }
 
+    /// <summary>
+    /// Sets the title of the application that will be rendered by the browser (e.g. the title of the tab).
+    /// </summary>
+    /// <param name="title">The title of the application to be set</param>
     public BrowserHandlerBuilder Title(string title)
     {
         _Title = title;

Modules/ApiBrowsing/Extensions.cs

@@ -0,0 +1,56 @@
+using GenHTTP.Modules.ApiBrowsing.Common;
+using GenHTTP.Modules.Layouting.Provider;
+
+namespace GenHTTP.Modules.ApiBrowsing;
+
+public static class Extensions
+{
+
+    /// <summary>
+    /// Creates a Swagger UI application and registers it at the layout.
+    /// </summary>
+    /// <param name="layout">The layout to add the application to</param>
+    /// <param name="segment">The path to make the application available from (defaults to "/swagger/")</param>
+    /// <param name="url">The URL of the Open API definition to be rendered (defaults to "../openapi.json")</param>
+    /// <param name="title">The title of the rendered application</param>
+    /// <returns>The layout once again (builder pattern)</returns>
+    /// <remarks>
+    /// There is no auto-detection of Open API definitions provided by the server
+    /// so the URL provided needs to point to the correct definition to be consumed.
+    /// Use relative paths to avoid issues with CORS, proxies etc.
+    /// </remarks>
+    public static LayoutBuilder AddSwaggerUI(this LayoutBuilder layout, string segment = "swagger", string? url = null, string? title = null)
+        => AddBrowser(layout, ApiBrowser.SwaggerUI(), segment, url, title);
+
+    /// <summary>
+    /// Creates a Redoc application and registers it at the layout.
+    /// </summary>
+    /// <param name="layout">The layout to add the application to</param>
+    /// <param name="segment">The path to make the application available from (defaults to "/redoc/")</param>
+    /// <param name="url">The URL of the Open API definition to be rendered (defaults to "../openapi.json")</param>
+    /// <param name="title">The title of the rendered application</param>
+    /// <returns>The layout once again (builder pattern)</returns>
+    /// <remarks>
+    /// There is no auto-detection of Open API definitions provided by the server
+    /// so the URL provided needs to point to the correct definition to be consumed.
+    /// Use relative paths to avoid issues with CORS, proxies etc.
+    /// </remarks>
+    public static LayoutBuilder AddRedoc(this LayoutBuilder layout, string segment = "redoc", string? url = null, string? title = null)
+        => AddBrowser(layout, ApiBrowser.Redoc(), segment, url, title);
+
+    private static LayoutBuilder AddBrowser(this LayoutBuilder layout, BrowserHandlerBuilder builder, string segment, string? url, string? title)
+    {
+        if (url != null)
+        {
+            builder.Url(url);
+        }
+
+        if (title != null)
+        {
+            builder.Title(title);
+        }
+
+        return layout.Add(segment, builder);
+    }
+
+}