[ASP.NET Core] .NET Core로 구현한 SPA(Single Page Applications)(5)

Swashbuckle.AspNetCore	ASP.NET Core Swagger 를 사용하기 위한 코어
Swashbuckle.AspNetCore.Swagger	SwaggerDocument 개체를 JSON 엔드포인트로 노출하기 위한 Swagger 개체 모델 및 미들웨어.
Swashbuckle.AspNetCore.SwaggerGen	경로, 컨트롤러 및 모델에서 직접 SwaggerDocument 개체를 빌드하는 Swagger 생성기. 일반적으로 Swagger 엔드포인트 미들웨어와 결합되어 자동으로 Swagger JSON을 노출합니다.
Swashbuckle.AspNetCore.SwaggerUI	Swagger UI 도구의 포함된 버전. Swagger JSON을 해석하여 웹 API 기능을 설명하기 위한 다양한 사용자 지정 가능한 환경을 빌드합니다. 여기에는 공용 메서드에 대한 기본 제공 테스트 도구가 포함됩니다.

2. 스워거 설정

'Startup.cs'의 'ConfigureServices'에 아래 코드를 추가합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//스웨거 문서정보를 생성 한다.
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1"
        , new Info 
        { 
            Title = "SPA NetCore Foundation API"
            , Description = "[ASP.NET Core] .NET Core로 구현한 SPA(Single Page Applications)(5) - 스웨거(Swagger) 설정 <br /> https://blog.danggun.net/7689"
            , Version = "v1"
            , Contact = new Contact
            {
                Name = "Dang-Gun Roleeyas",
                Email = string.Empty,
                Url = "https://blog.danggun.net/"
            }
            , License = new License
            {
                Name = "MIT",
                Url = "https://opensource.org/licenses/MIT"
            }
        });
});
Colored by Color Scripter
cs

'Configure'에는 다음 코드를 추가합니다.

1
2
3
4
5
6
7
8
9
//스웨거 미들웨어 설정
app.UseSwagger();
 
//스웨거 UI 활성화
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    //c.RoutePrefix = string.Empty;
});
Colored by Color Scripter
cs

실행하고 주소 뒤에 'swagger'를 붙이면 스웨거가 생성해준 페이지가 실행됩니다.

2-2. 주석 표시 기능 사용하기

주석을 스웨거에 표시할 수 있습니다.

프로젝트 속성 > 빌드 > 출력

'XML 문서 파일' 옵션을 체크 합니다.

경로를 "\SPA_NetCore_Foundation05.xml"와 같이 해줍니다.

'Startup.cs' 파일에서 'ConfigureServices'함수에 위에서 추가한 'services.AddSwaggerGen'코드 안에 아래 코드를 추가합니다.

1
2
//주석 표시기능
c.IncludeXmlComments(string.Format(@"{0}\SPA_NetCore_Foundation05.xml", System.AppDomain.CurrentDomain.BaseDirectory));
cs

이제 테스트를 해봅시다.

3. 인증 토큰 사용

엑세스 토큰(access token)이 필요한 API의 경우 토큰을 미리 입력할수 있는 UI를 제공해야 합니다.

'Startup.cs'의 'c.SwaggerDoc'선언 끝에 아래 코드를 추가합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
//인증UI **************************************
c.AddSecurityDefinition("Bearer", new ApiKeyScheme
{
    In = "header",
    Description = "로그인 후 전달받은 'ExternalKey'를 헤더의'MgrExternalKey' 담아 전달해야 합니다.",
    Name = "Authorization",
    Type = "apiKey"
});
 
c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>>
{
    { "Bearer", new string[] { } }
});
Colored by Color Scripter
cs