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'를 붙이면 스웨거가 생성해준 페이지가 실행됩니다.




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를 공개했을 때 문서 양이 확 줄어듭니다.

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

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

댓글 작성

이름
패스워드
홈페이지
비밀글