c# 최신버전으로 Rest API 를 작성하는 강좌입니다. 지극히 주관적이면 제가 아는 Knowhow의 입각한 강좌입니다.

---

Project 생성

당연히 API 프로젝트를 생성합니다.

프로젝트명과 이름은 알맞게 지어주세요

.Net 7.0을 사용하고 option 위와 같이 하겠습니다.

---

Solution

프로젝트를 생성하고 솔루션 구조는 아래와 같습니다. 지극히 주관적이고 저의 knowhow
입각한 구조입니다.

설명

프로젝트명	설명
API_Tutorial	Controller 모음 api의 노출 프로젝트
API_Tutorial.Application	Business Logic 을 구성
API_Tutorial.Domain	Database 의 Model 구성
API_Tutorial.Infra	이 솔루션의 기반 사용하는 library의 설정
API_Tutorial.Shared	API 구독자와의 contract model

강좌를 위해 최대한 간략한 구조입니다. 컨셉은 Clean Archtecture 입니다.
(https://jasontaylor.dev/clean-architecture-getting-started/)
정석은 아닐지 몰라도 저 나름대로의 해석과 이해를 바탕으로 구성했습니다.

Nuget USE

이제 당연히 library 구성해야겠죠? 자세한 nuget구성은 github 소스를 참조해주세요

대표적인 library는
AutoMapper,Dapper,MediatR, Mapster,Serilog 등등이 있습니다.

---

Cofiguration 구성

보통 appsettings.json 모든 설정을 합쳐 구성하지만 저는 가독성과 유지보수를 위해서 config 를 분할합니다.

 internal static ConfigureHostBuilder AddConfigurations(this ConfigureHostBuilder host)
    {
        host.ConfigureAppConfiguration((context, config) =>
        {
            const string configurationsDirectory = "Configurations";
            var env = context.HostingEnvironment;
            config.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
                .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: true)
                .AddJsonFile($"{configurationsDirectory}/logger.json", optional: false, reloadOnChange: true)
                .AddJsonFile($"{configurationsDirectory}/logger.{env.EnvironmentName}.json", optional: true, reloadOnChange: true)                
                .AddJsonFile($"{configurationsDirectory}/cache.json", optional: false, reloadOnChange: true)
                .AddJsonFile($"{configurationsDirectory}/cache.{env.EnvironmentName}.json", optional: true, reloadOnChange: true)
                .AddJsonFile($"{configurationsDirectory}/cors.json", optional: false, reloadOnChange: true)
     
                .AddEnvironmentVariables();
        });
        return host;
    }

이런식으로 config json을 한개씩 참조하고 각설정을 json으로 분산했습니다.

---

Base Class

상속받는 class 를 정의하겠습니다.

[ApiController]
public class BaseApiController : ControllerBase
{
    private ISender _mediator = null!;
    protected ISender Mediator => _mediator ??= HttpContext.RequestServices.GetRequiredService<ISender>();
}

모든 Controller가 상속 받는 class 입니다. 당연히 ControllerBase
CQRS 패턴을 위해 _mediator 종속성을 넣겠습니다.
또 base class를 당시 상속 받아

VersionedApiController.cs
[Route("api/v{version:apiVersion}/[controller]")]
public class VersionedApiController : BaseApiController
{
}

VersionNeutralApiController.cs
[Route("api/[controller]")]
[ApiVersionNeutral]
public class VersionNeutralApiController : BaseApiController
{
}

별다른 차이없는 class를 다시 두개로 정의한 이유는 version 관리를 위해
일단 분류했다고 보면 됩니다.

---

Swagger 구성

기본적으로 project 생성시에 swaggr 생성이 default 로 깔리나
좀더 강력한 기능을 위해 custom 구성을 해보겠습니다. 설명이 자세하지 못한것은
이것 하나로도 강좌가 하나 나올정도로 양이 좀 많은점 이해 바랍니다.

 public static IServiceCollection AddOpenApiDocumentation(this IServiceCollection services, IConfiguration config)
    {
        var settings = config.GetSection(nameof(SwaggerSettings)).Get<SwaggerSettings>();
        if (settings.Enable)
        {
            services.AddVersionedApiExplorer(o => o.SubstituteApiVersionInUrl = true);
            services.AddEndpointsApiExplorer();
            services.AddOpenApiDocument((document, serviceProvider) =>
            {
                document.PostProcess = doc =>
                {
                    doc.Info.Title = settings.Title;
                    doc.Info.Version = settings.Version;
                    doc.Info.Description = settings.Description;
                    doc.Info.Contact = new()
                    {
                        Name = settings.ContactName,
                        Email = settings.ContactEmail,
                        Url = settings.ContactUrl
                    };
                    doc.Info.License = new()
                    {
                        Name = settings.LicenseName,
                        Url = settings.LicenseUrl
                    };
                };
                document.AddSecurity(JwtBearerDefaults.AuthenticationScheme, new OpenApiSecurityScheme
                {
                    Name = "Authorization",
                    Description = "Input your Bearer token to access this API",
                    In = OpenApiSecurityApiKeyLocation.Header,
                    Type = OpenApiSecuritySchemeType.Http,
                    Scheme = JwtBearerDefaults.AuthenticationScheme,
                    BearerFormat = "JWT",
                });
                document.OperationProcessors.Add(new AspNetCoreOperationSecurityScopeProcessor());
                document.OperationProcessors.Add(new SwaggerGlobalAuthProcessor());
                document.TypeMappers.Add(new PrimitiveTypeMapper(typeof(TimeSpan), schema =>
                {
                    schema.Type = NJsonSchema.JsonObjectType.String;
                    schema.IsNullableRaw = true;
                    schema.Pattern = @"^([0-9]{1}|(?:0[0-9]|1[0-9]|2[0-3])+):([0-5]?[0-9])(?::([0-5]?[0-9])(?:.(\d{1,9}))?)?$";
                    schema.Example = "02:00:00";
                }));
                document.OperationProcessors.Add(new SwaggerHeaderAttributeProcessor());
                var fluentValidationSchemaProcessor = serviceProvider.CreateScope().ServiceProvider.GetService<FluentValidationSchemaProcessor>();
                document.SchemaProcessors.Add(fluentValidationSchemaProcessor);
            });
            services.AddScoped<FluentValidationSchemaProcessor>();
        }
        return services;
    }


    public static IApplicationBuilder UseOpenApiDocumentation(this IApplicationBuilder app, IConfiguration config)
    {
        if (config.GetValue<bool>("SwaggerSettings:Enable"))
        {
            app.UseOpenApi();
            app.UseSwaggerUi3(options =>
            {
                options.DefaultModelsExpandDepth = -1;
                options.DocExpansion = "none";
                options.TagsSorter = "alpha";               
            });
        }
        return app;
    }

이와같이 구성하고

 public static IServiceCollection AddInfrastructure(this IServiceCollection services, IConfiguration config)
    {
        var assembly = Assembly.GetExecutingAssembly();
        services.AddValidatorsFromAssembly(assembly)
            .AddMediatR(assembly)
            .AddApplicationInfrastructure(config);
        return services
            .AddApiVersioning()           
            .AddOpenApiDocumentation(config)                       
            .AddRouting(options => options.LowercaseUrls = true);
    }
    
    
    public static IApplicationBuilder UseInfrastructure(this IApplicationBuilder builder, IConfiguration config)
    {
        return builder
                   .UseRequestLocalization()
                   .UseStaticFiles()                   
                   .UseHttpsRedirection()
                   .UseRouting()                   
                   .UseAuthentication()
                   .UseAuthorization()                   
                   .UseOpenApiDocumentation(config);
    }    

program.cs에서 사용선언을 합니다.

---

최초 Controller 작성

BoardController.cs 를 한번 작성해보겠습니다.

public class BoardController : VersionedApiController
{
    [HttpGet]    
    [Route("t1")]
    [AllowAnonymous]
    public async Task<IActionResult> Get1()
    {        
        return Ok("Hello world");
    }
}

VersionedApiController 을 상속하고
Method는 그냥 hellow world를 찍게 작성하겠습니다.

---

최초 실행

여기까지 하고 ctlr+f5 실행하면

swagger api ui 가 나옵니다. 좀 다른점이 있다면 header 설정이 가능한 ui 죠

처음에 의욕차게 한번에 끝내볼려고 했던 강좌이나 너무너무 방대해져서 며칠에 걸쳐
하나씩 완성해나가야할것 같습니다. 하다보니까 강좌가 10개는 넘게 나올것 같군요 ㅎㅎ

github:
https://github.com/BlueBirdJun/API_Tutorial.git