[.NET Core] .NET Core 3.1 - Swagger 적용

개발에 있어서 중요한 부분중 하나는 문서화 능력이라고 생각하고 있습니다. 물론 실천하기는 어렵지만, 누구나 시스템에 대한 기본 이해도를 높일 수 있는 문서는 최소한으로 제공해야 한다가 저의 소신 중 하나입니다. 

그래서 시간이 날때마다, 이런 내용을 수시로 기록하려고 노력하고 있습니다.

 

RESTFul API를 제작하다 보면 더더욱 그런데요. 

이를 간편하게 제공해줄수 있는 Swagger란 프레임워크를 많이들 사용하는 걸로 알고 있습니다. 

.NET Core 에서 Swagger를 사용하는 방법에 대해서, 정리하였습니다. 

스웨거(Swagger)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 오픈 소스 소프트웨어 프레임워크입니다. 
대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.

 

---

1. Swagger 설치

Nuget Package 를 이용해서 설치할 수 있으며, 아래의 패키지를 설치 하시 면 됩니다. 

제가 설치 할 당시 5.4.1 버전 이였습니다. 

 

 

---

2. ConfigureServices 설정

services.AddSwaggerGen 메소드를 이용해서 Swagger를 설정 할 수 있습니다. 

기본적으로

c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

 

위 내용만으로도 설정이 가능하지만, 여러 형태의 문서를 사용하실 경우 아래와 같이 이용하시면 됩니다. 

저는 기본 api 문서와 admin 영역의 api를 분리해서 가공하였습니다. 

public void ConfigureServices(IServiceCollection services)
{
	...
    
    services.AddSwaggerGen(c =>
    {
        //c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        c.SwaggerDoc("api", new OpenApiInfo
        {
            Title = "문서의 제목",
            Description = "문서의 설명",
            Contact = new OpenApiContact
            {
                Name = "서버 정보 - Server Gitlab",
                Email = string.Empty,
                Url = new Uri("http://xxx.xxx.xxx.xxx")
            }
        });
        c.SwaggerDoc("admin", new OpenApiInfo
        {
            Title = "관리자 Title",
            Description = "관리자 DESC",
            Contact = new OpenApiContact
            {
                Name = "서버 정보 - Server Gitlab",
                Email = string.Empty,
                Url = new Uri("http://000.000.000.000")
            }
        });
    });
}

 

 

---

3. Configure 설정

app에서 Swaggerd와 SwaggerUI를 사용으로 등록해주고, 

SwaggerUI의 경우, 위에서 두가지 문서로 사용할 예정이여서 API 그룹과 Admin 그룹으로 분리해서 등록하였습니다. 

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
        app.UseHsts();
    }

    .. 중략 ..

    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        //c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.SwaggerEndpoint("/swagger/api/swagger.json", "Api Documents");
        c.SwaggerEndpoint("/swagger/admin/swagger.json", "Admin Documents");
    });

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

 

 

---

3. 실행화면

실행되는 웹사이트 주소 뒤에 /swagger 를 붙여주면 Swagger의 UI 화면을 보실 수 있습니다. 

 

 

 

 

---

TIP

위 처럼 그룹을 분리해서 사용해주고 싶으실 경우에는 ApiExplorerSettings Attribute를 이용해서 그룹화 해주면 되는데요.

아래와 같이 이용해서 그룹을 분리해주시면 됩니다. 

[HttpPost]
[ApiExplorerSettings(GroupName = "admin")]
public ActionResult Add()
{
}