ASPNET 7 - Route Group and Swagger

MapGroup 를 통해 엔드포인트 그룹을 구성하는 데 도움이 된다. 

반복 코드를 줄이고 특정 Method 들을 단일 호출 하는데 사용가능 하다.

 

아래와 같이 사용한다.

var route = app.MapGroup("/route")

이 의미는 route 라는 MapGroup 을 만들고 경로는 "/route" 라는 의미 이다. 

여기에 다음과 같은 코드를 추가해 보자

route.MapGet("/", () =>
{
    return $"Hello!! {DateTime.Now.Ticks}";
});

이 코드는  /route 에 http get method 가 호출 되면 실행된다. 

아래 코드도 추가해 보자

route.MapGet("/user", (string name) =>
{
    return $"Hello!! {name}";
});

이 코드는 /route/user 에 http get method 가 호출 되면 실행된다. 

 

즉 route 라는 base url (여기서는 route) 을 이용하여 상대적으로 각각의 url 을 구성할 수 있다는 것이다

 

만약 두 api 에 한꺼번에 인증이 돼야만 접근할 수 있게 하려면 아래와 같이 group 에 추가한다.

var route = app.MapGroup("/route")
           .RequireAuthorization(); // route group 전체에 인증 요구

이렇게 하면 route 를 사용한 group 의 api 는 모두 인증을 요구한다. 

 

Swagger 를 통한 문서화 (Response type)

 

swagger 는 기본적으로 문서화 작업을 해주는데

특정한 response 는 swagger 가 자동으로 인식 하지 못한다.

아래 코드를 보자

var noAuth = app.MapGroup("/no-auth");

noAuth.MapGet("/",  ([AsParameters]BaseRequest request) =>
{
    return request.Id == "1" 
    ? Results.NotFound()
    : Results.Ok(new BaseResponse 
    { 
        Result = true ,
        ErrorMessage = $"{request.Id} , Success"
    });
});

코드 실행 시 swagger 에서 response 에 대한 추론을 하지 못한다. 

 

 

자동으로 인식하게 하기 위해 hint 를 줄 수 있다. 

noAuth.MapGet("/",  ([AsParameters]BaseRequest request) =>
{
    return request.Id == "1" 
    ? Results.NotFound()
    : Results.Ok(new BaseResponse 
    { 
        Result = true ,
        ErrorMessage = $"{request.Id} , Success"
    });
}).Produces<BaseResponse>(); // hint 추가

그러면 다음과 같이 Schemas 가 추가 되고 Response 에 type 도 인식한다. 

 

여러 응답 유형을 지정 할 수도 있다. 

.Produces<BaseResponse>(StatusCodes.Status200OK) // 정상처리라면 실행
.Produces(StatusCodes.Status404NotFound); // not found 라면 이것 실행

TypedResults 를 통한 유형 지정

 

위예제는 Results<T, T2> 형태로 지정해서 Produces 없이 swagger 에 response  type 을 전달 할 수 있다. 

swagger 에 정보 전달은 TypedResults 를 이용한다. 

noAuth.MapGet("/type-result", Results<NotFound, Ok<BaseResponse>> ([AsParameters] BaseRequest request) =>
{
    return request.Id == "1"
    ? TypedResults.NotFound()
    : TypedResults.Ok(new BaseResponse
    {
        Result = true,
        ErrorMessage = $"{request.Id} , Success"
    });
});

위와 같이 지정할 경우 produces 없이 같은 동작을 하도록 할 수 있다. 

 

관련영상

https://youtu.be/q2-hgWp3Ghw