2019. 12. 5. 15:30

WebAPI를 쓴다면 스웨거를 빼놓을 수 없습니다.

스웨거는 WebAPI 문서를 자동화 해주는 해주는 라이브러리입니다.

( 참고 : 위키백과 - 스웨거 (소프트웨어) )


문서화뿐만 아니라 바로 테스트도 할 수 있으므로 프론트엔드 개발자와 소통이 편해지죠.




1. 스웨거 설치

누겟에서 다음 4개를 찾아서 설치합니다.

버전은 4.x 를 설치합니다.

( 참고 : microsoft docs - Swashbuckle 및 ASP.NET Core 시작 )


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"
            }
        });
});
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;
});
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[] { } }
});
cs



이제 스웨거의 오른쪽에 'Authorize' 버튼이 생깁니다.

이 버튼을 누르면 인증키를 입력할 수 있는 UI가 표시됩니다.


여기에 

Bearer [access token]

형식으로 키를 입력합니다.






엑세스 토큰이 있어야 하는 API는 '/api/Test/Test02'입니다.

이걸 호출합니다.




헤더에 값이 정확하게 들어갔습니다.


결과도 잘 나오네요.




오류 1. Fetch error : Internal Server Error

오류 내용은 아래와 같습니다.


Fetch error 

Internal Server Error /swagger/v1/swagger.json




컨트롤러에 메소드를 잘못지정하면 나는 오류입니다.

적절한 메소드를 지정해 줍시다.







마무리

완성된 샘플 : Github dang-gun - SPA_NetCore_Foundation/SPA_NetCore_Foundation/SPA_NetCore_Foundation05/


스웨거만 연결해놔도 프론트엔드(front-end)나 외부로 API를 공개했을 때 문서 양이 확 줄어듭니다.

거기다 다른 사람이 직접 호출해서 테스트할 수 있으니 잘못된 동작이 있으면 빠르게 피드백이 가능해집니다.

우리 모두 오픈소스의 축복을!