Add Swagger Support

Author: RickStrahl

src/AlbumViewerNetCore/Controllers/AccountController.cs

@@ -18,6 +18,14 @@
 
 namespace AlbumViewerAspNetCore
 {
+    /// <summary>
+    /// Token Authentication class
+    ///
+    /// This class uses a manually created bearer token via Authenticate
+    /// that is used to validate each request. If validated the User.Identity
+    /// is updated as appropriate and can be used in [Authorize] access control
+    /// or manual token validation by the APIs in this class.
+    /// </summary>
     [Authorize()]
     [ServiceFilter(typeof(ApiExceptionFilter))]
     public class AccountController : Controller
@@ -44,6 +52,8 @@ public AccountController(AccountRepository actRepo,
         /// </summary>
         /// <param name="loginUser"></param>
         /// <returns></returns>
+        /// <response code="200">Authenticated</response>
+        /// <response code="401">Invalid or missing credentials</response>
         [AllowAnonymous]
         [HttpPost]
         [Route("api/authenticate")]
@@ -82,7 +92,11 @@ public async Task<object> Authenticate([FromBody] User loginUser)
             };
         }
 
-
+        /// <summary>
+        /// Logs out the current user by immediately expiring the user's
+        /// active token.
+        /// </summary>
+        /// <returns></returns>
         [AllowAnonymous]
         [HttpGet]
         [Route("api/logout")]
@@ -97,6 +111,10 @@ public  bool Logout()
             return true;
         }
 
+        /// <summary>
+        /// Returns true or false depending on whether user is authenticated.
+        /// </summary>
+        /// <returns></returns>
         [HttpGet]
         [Route("api/isAuthenticated")]
         public bool IsAuthenthenticated()
@@ -145,6 +163,7 @@ private void RemoveExpiredTokens()
         /// <returns></returns>
         [AllowAnonymous]
         [HttpPost]
+        [Obsolete("Left here only for reference. Use Token Authentication instead.")]
         [Route("api/login")]
         public async Task<bool> Login([FromBody] User loginUser)
         {

src/AlbumViewerNetCore/Controllers/AlbumViewerApiController.cs

@@ -51,19 +51,17 @@ public AlbumViewerApiController(
             HostingEnv = env;
         }
 
-      
 
-
-        [HttpGet]
-        [Route("api/throw")]
-        public object Throw()
-        {
-            throw new InvalidOperationException("This is an unhandled exception");            
-        }
-
-        
         #region albums
 
+        /// <summary>
+        /// A list of albums with detail artist data
+        /// </summary>
+        /// <param name="page"></param>
+        /// <param name="pageSize"></param>
+        /// <returns></returns>
+        /// <response code="200">Album List</response>
+        /// <response code="500">Failed to retrieve albums</response>
         [HttpGet]
         [Route("api/albums")]
         public async Task<IEnumerable<Album>> GetAlbums(int page = -1, int pageSize = 15)
@@ -72,12 +70,23 @@ public async Task<IEnumerable<Album>> GetAlbums(int page = -1, int pageSize = 15
             return await AlbumRepo.GetAllAlbums(page, pageSize);
         }
 
+        /// <summary>
+        /// Returns an individual album
+        /// </summary>
+        /// <param name="id"></param>
+        /// <returns></returns>
         [HttpGet("api/album/{id:int}")]
         public async Task<Album> GetAlbum(int id)
         {
             return await AlbumRepo.Load(id);
         }
 
+        /// <summary>
+        /// Update or add a new album
+        /// </summary>
+        /// <param name="postedAlbum"></param>
+        /// <returns></returns>
+        /// <exception cref="ApiException"></exception>
         [HttpPost("api/album")]
         public async Task<Album> SaveAlbum([FromBody] Album postedAlbum)
         {
@@ -103,6 +112,13 @@ public async Task<Album> SaveAlbum([FromBody] Album postedAlbum)
             return album;
         }
 
+
+        /// <summary>
+        /// Delete a specific album by id
+        /// </summary>
+        /// <param name="id"></param>
+        /// <returns></returns>
+        /// <exception cref="ApiException"></exception>
         [HttpDelete("api/album/{id:int}")]
         public async Task<bool> DeleteAlbum(int id)
         {
@@ -113,6 +129,12 @@ public async Task<bool> DeleteAlbum(int id)
         }
 
 
+        /// <summary>
+        /// Delete an album by its album name
+        /// </summary>
+        /// <param name="name"></param>
+        /// <returns></returns>
+        /// <exception cref="ApiException"></exception>
         [HttpGet]
         public async Task<string> DeleteAlbumByName(string name)
         {
@@ -139,13 +161,23 @@ await context.Albums
 
         #region artists
 
+        /// <summary>
+        /// Return a list of Artists
+        /// </summary>
+        /// <returns></returns>
         [HttpGet]
         [Route("api/artists")]
         public async Task<IEnumerable> GetArtists()
         {
             return await ArtistRepo.GetAllArtists();
         }
 
+        /// <summary>
+        /// Return an individual Artist
+        /// </summary>
+        /// <param name="id"></param>
+        /// <returns></returns>
+        /// <exception cref="ApiException"></exception>
         [HttpGet("api/artist/{id:int}")]
         public async Task<object> Artist(int id)
         {
@@ -163,6 +195,12 @@ public async Task<object> Artist(int id)
             };
         }
 
+        /// <summary>
+        /// Update or add a new Artist
+        /// </summary>
+        /// <param name="artist"></param>
+        /// <returns></returns>
+        /// <exception cref="ApiException"></exception>
         [HttpPost("api/artist")]
         public async Task<ArtistResponse> SaveArtist([FromBody] Artist artist)
         {
@@ -187,6 +225,11 @@ public async Task<ArtistResponse> SaveArtist([FromBody] Artist artist)
             };
         }
 
+        /// <summary>
+        /// Look up an artist by name (search functionality)
+        /// </summary>
+        /// <param name="search"></param>
+        /// <returns></returns>
         [HttpGet("api/artistlookup")]
         public async Task<IEnumerable<object>> ArtistLookup(string search = null)
         {
@@ -199,6 +242,12 @@ public async Task<IEnumerable<object>> ArtistLookup(string search = null)
         }
 
 
+        /// <summary>
+        /// Delete an individual artist by Id
+        /// </summary>
+        /// <param name="id"></param>
+        /// <returns></returns>
+        /// <exception cref="ApiException"></exception>
         [HttpDelete("api/artist/{id:int}")]
         public async Task<bool> DeleteArtist(int id)
         {
@@ -210,6 +259,20 @@ public async Task<bool> DeleteArtist(int id)
 
         #endregion
 
+        /// <summary>
+        /// Sample endpoint that explicitly raises an exception to
+        /// demonstrate default error results.
+        /// </summary>
+        /// <returns></returns>
+        /// <exception cref="InvalidOperationException"></exception>
+        /// <response code="500">Unhandled exception thrown - error response</response>
+        [HttpGet]
+        [Route("api/throw")]
+        public object Throw()
+        {
+            throw new InvalidOperationException("This is an unhandled exception");            
+        }
+
         #region admin
         [HttpGet]
         [Route("api/reloaddata")]

src/AlbumViewerNetCore/Controllers/ConfigurationController.cs

@@ -35,6 +35,10 @@ public ConfigurationController(IOptions<ApplicationConfiguration> configuration,
         }
 
 
+        /// <summary>
+        /// Returns the application configuration settings
+        /// </summary>
+        /// <returns></returns>
         [HttpGet]
         [Route("api/configuration")]
         public ApplicationConfiguration GetConfiguration()
@@ -43,6 +47,11 @@ public ApplicationConfiguration GetConfiguration()
         }
 
 
+
+        /// <summary>
+        /// Provides information about the running application
+        /// </summary>
+        /// <returns></returns>
 	    [HttpGet("api/applicationstats")]
         public object GetApplicationStats()
         {
@@ -58,13 +67,12 @@ public object GetApplicationStats()
             string useSqLite = RawConfiguration["Data:useSqLite"];
 
             // in 3.0 this might work - 2.2: SERIOUSLY????
-            string runtime = System.Runtime.InteropServices.RuntimeInformation.FrameworkDescription;
+            //string runtime = System.Runtime.InteropServices.RuntimeInformation.FrameworkDescription;
 
             var stats = new
             {
                 OsPlatform = System.Runtime.InteropServices.RuntimeInformation.OSDescription,
-                AspDotnetVersion = vname + " (" +
-                                   System.Runtime.InteropServices.RuntimeInformation.ProcessArchitecture.ToString().ToLower() + ")",
+                AspDotnetVersion = System.Runtime.InteropServices.RuntimeInformation.FrameworkDescription,
                 DataMode = useSqLite == "true" ? "SqLite" : "Sql Server"
             };
 
@@ -73,11 +81,7 @@ public object GetApplicationStats()
 
 
         /// <summary>
-        /// Allow Lets Encrypt Reneawal requests through the pipeline by 
-        /// default these are twarthed because they are treated as extensionless
-        /// action route urls (which have no match and fail).
-        /// 
-        /// Explicitly map a route to the URL and then serve the physical file
+        /// Explicit endpoint to handle LetsEncryt certificate requests
         /// </summary>
         /// <param name="id"></param>
         /// <returns></returns>

src/AlbumViewerNetCore/Program.cs

@@ -15,6 +15,7 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.IdentityModel.Tokens;
+using Microsoft.OpenApi.Models;
 
 
 var builder = WebApplication.CreateBuilder(args);
@@ -109,6 +110,31 @@
             opt.SerializerSettings.Formatting = Newtonsoft.Json.Formatting.Indented;
     });
 
+
+builder.Services.AddSwaggerGen(options =>
+{
+    options.SwaggerDoc("v1", new OpenApiInfo
+    {
+        Version = "v1",
+        Title = "License Manager API",
+        Description = "West Wind Album Viewer",
+        //TermsOfService = new Uri("https://example.com/terms"),
+        //Contact = new OpenApiContact
+        //{
+        //    Name = "Example Contact",
+        //    Url = new Uri("https://example.com/contact")
+        //},
+        //License = new OpenApiLicense
+        //{
+        //    Name = "Example License",
+        //    Url = new Uri("https://example.com/license")
+        //}
+    });
+
+    var filePath = Path.Combine(System.AppContext.BaseDirectory, "AlbumViewerNetCore.xml");
+    options.IncludeXmlComments(filePath);
+});
+
 //
 // *** BUILD THE APP
 //
@@ -189,6 +215,14 @@ await context.Response.WriteAsync(
     app.MapControllers();
 });
 
+
+// for this app make it public
+if (true)  // (app.Environment.IsDevelopment()) 
+{
+    app.UseSwagger();
+    app.UseSwaggerUI();
+}
+
 // catch-all handler for HTML5 client routes - serve index.html
 app.Run(async context =>
 {
@@ -221,5 +255,4 @@ AlbumViewer Core
 
 
 
-
 app.Run();

src/AlbumViewerNetCore/appsettings.json

@@ -25,7 +25,9 @@
 
     "Logging": {
         "LogLevel": {
-            "Default": "Error"
+            "Default": "Warning",
+            "Microsoft": "Warning",
+            "Microsoft.Hosting.Lifetime": "Warning"
         }
     }
 }