docs: benahi swagger preparation agar nantinya bisa generate contract dengan example dan security scheme yang benar

Author: hezbims

Inv_Backend_NET/Fitur/Autentikasi/Login/LoginController.cs

@@ -2,8 +2,11 @@
 using Inventory_Backend_NET.Database;
 using Inventory_Backend_NET.Fitur._Logic.Services;
 using Inventory_Backend_NET.Fitur.Autentikasi._Dto.Response;
+using JetBrains.Annotations;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
+using Swashbuckle.AspNetCore.Annotations;
+using Swashbuckle.AspNetCore.Filters;
 
 namespace Inventory_Backend_NET.Fitur.Autentikasi.Login
 {
@@ -22,7 +25,11 @@ IJwtTokenService jwtTokenService
 
         [HttpPost]
         [AllowAnonymous]
-        public IActionResult Login([FromBody] LoginBodyDto user)
+        [SwaggerResponse(StatusCodes.Status200OK, "Login Sukses", typeof(LoginSucceedResponse))]
+        [SwaggerResponseExample(StatusCodes.Status200OK, typeof(LoginSucceedResponseExample))]
+        [SwaggerResponse(StatusCodes.Status400BadRequest, "Login gagal", typeof(LoginFailedResponse))]
+        [SwaggerResponseExample(StatusCodes.Status400BadRequest, typeof(LoginFailedResponseExample))]
+        public IActionResult Login([FromBody] LoginRequest user)
         {
             var currentUser = _db.Users.FirstOrDefault( 
                 predicate: aUser => 
@@ -32,28 +39,56 @@ public IActionResult Login([FromBody] LoginBodyDto user)
 
             if (currentUser == null)
             {
-                return BadRequest(new { message = "Username atau password salah" });
+                return BadRequest(new LoginFailedResponse(Message: "Username atau password salah" ));
             } else
             {
-                return Ok(new
-                {
-                    message = "Sukses",
-                    token = _jwtTokenService.GenerateNewToken(currentUser),
-                    user = GetUserDto.From(currentUser)
-                });
+                return Ok(new LoginSucceedResponse
+                (
+                    Message: "Sukses",
+                    Token: _jwtTokenService.GenerateNewToken(currentUser),
+                    User: GetUserDto.From(currentUser)
+                ));
             }
         }
 
 
     }
+
+    internal record LoginSucceedResponse(
+        [property: JsonPropertyName("token")][UsedImplicitly] string Token,
+        [property: JsonPropertyName("user")][UsedImplicitly] GetUserDto User,
+        [property: JsonPropertyName("message")][UsedImplicitly] string Message);
+
+    internal record LoginFailedResponse(
+        [property: JsonPropertyName("message")][UsedImplicitly] string Message);
 
-    public class LoginBodyDto
+    public class LoginRequest
     {
         [JsonPropertyName("username")] 
         public string Username { get; set; } = null!;
 
         [JsonPropertyName("password")] 
         public string Password { get; set; } = null!;
     }
+
+    file class LoginSucceedResponseExample : IExamplesProvider<LoginSucceedResponse>
+    {
+        public LoginSucceedResponse GetExamples()
+        {
+            return new LoginSucceedResponse(
+                Token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6ImFkbWluIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoiQWRtaW4iLCJleHAiOjE3NjgyNzE0MDEsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6NTE1NCIsImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMCJ9.H46pIQejekT9s-GuXsEauIqGjK2zu2vitYyWAhLRu8Y",
+                User: new GetUserDto(id: 1, username: "admin", isAdmin: true),
+                Message: "Sukses"
+            );
+        }
+    }
+
+    file class LoginFailedResponseExample : IExamplesProvider<LoginFailedResponse>
+    {
+        public LoginFailedResponse GetExamples()
+        {
+            return new LoginFailedResponse(Message: "Username atau password salah");
+        }
+    }
 }
 

Inv_Backend_NET/Inventory_Backend_NET.csproj

@@ -12,6 +12,7 @@
     <PackageReference Include="CSVHelper" Version="30.0.1" />
     <PackageReference Include="dotenv.net" Version="3.1.3" />
     <PackageReference Include="EntityFrameworkCore.Exceptions.SqlServer" Version="8.1.3" />
+    <PackageReference Include="JetBrains.Annotations" Version="2025.2.4" />
     <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.0" />
     <PackageReference Include="Microsoft.AspNetCore.SpaServices.Extensions" Version="8.0.0" />
     <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.13" />
@@ -25,6 +26,7 @@
     <PackageReference Include="Serilog" Version="4.2.0" />
     <PackageReference Include="Serilog.Sinks.File" Version="7.0.0" />
     <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
+    <PackageReference Include="Swashbuckle.AspNetCore.Filters" Version="6.1.0" />
     <PackageReference Include="System.IdentityModel.Tokens.Jwt" Version="7.0.3" />
   </ItemGroup>
 

Inv_Backend_NET/Program.cs

@@ -13,7 +13,7 @@ public static void Main(string[] args)
 
         builder
             .PrepareDependencyInjectionServices()
-            .PrepareSwaggerWithJwtInputService()
+            .PrepareSwagger()
             .PrepareAuthenticationServices()
             .PrepareCorsServices()
             .PrepareMonitongServices()
@@ -27,11 +27,11 @@ public static void Main(string[] args)
         var containsSeederKeyword = app.HandleSeedingCommandFromCli(args: args);
         if (containsSeederKeyword) return;
 
-        if (app.Environment.IsDevelopment())
+        if (app.Environment.IsEnvironment("Local"))
         {
-            app.UseSwagger();
             app.UseSwaggerUI();
         }
+        app.UseSwagger();
         app.UseWebSockets();
         app.UseHttpsRedirection();
         app.UseCors();

Inv_Backend_NET/Startup/PrepareSwaggerExtension.cs

@@ -0,0 +1,83 @@
+using System.Reflection;
+using JetBrains.Annotations;
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc.Controllers;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.Filters;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace Inventory_Backend_NET.Startup;
+
+public static class PrepareSwaggerExtension
+{
+    public static WebApplicationBuilder PrepareSwagger(this WebApplicationBuilder builder)
+    {
+        builder.Services.AddSwaggerGen(option =>
+        {
+            option.SwaggerDoc("v1", new OpenApiInfo
+            {
+                Version = "1.0.0",
+                Title = "Inventory System API Specification"
+            });
+            
+            option.AddSecurityDefinition(name: JwtBearerDefaults.AuthenticationScheme , new OpenApiSecurityScheme
+            {
+                In = ParameterLocation.Header,
+                Description = "Masukkan token",
+                Name = "Authorization",
+                Type = SecuritySchemeType.Http,
+                BearerFormat = "JWT",
+                Scheme = JwtBearerDefaults.AuthenticationScheme
+            });
+            option.OperationFilter<AllowAnonymousOperationFilter>();
+            
+            option.EnableAnnotations();
+            option.ExampleFilters();
+            option.SupportNonNullableReferenceTypes();
+        });
+        
+        builder.Services.AddSwaggerExamplesFromAssemblyOf<Program>();
+        
+        return builder;
+    }
+    
+    
+    [UsedImplicitly]
+    private class AllowAnonymousOperationFilter : IOperationFilter
+    {
+        public void Apply(OpenApiOperation operation, OperationFilterContext context)
+        {
+            var methodAttributes = context.ApiDescription.CustomAttributes().ToArray();
+            var controllerAttributes = (context.ApiDescription.ActionDescriptor as ControllerActionDescriptor)
+                ?.ControllerTypeInfo
+                .GetCustomAttributes()
+                .ToArray();
+            
+            bool methodAllowAnonymous = methodAttributes.Any(attr => attr is AllowAnonymousAttribute);
+            bool controllerAllowAnonymous = controllerAttributes?.Any(attr => attr is AllowAnonymousAttribute) == true;
+
+            if (methodAllowAnonymous || controllerAllowAnonymous)
+                return;
+            
+            operation.Security =
+            [
+                new OpenApiSecurityRequirement
+                {
+                    {
+                        new OpenApiSecurityScheme
+                        {
+                            Reference = new OpenApiReference
+                            {
+                                Type = ReferenceType.SecurityScheme,
+                                Id = JwtBearerDefaults.AuthenticationScheme // sesuaikan sama cheme di security definition
+                            }
+                        },
+                        []
+                    }
+                }
+            ];
+        }
+    }
+
+}