스웨거

웹에이피아이 프로젝트를 생성하면 자동으로 스웨거라는 패키지가 추가됩니다. 스웨거는 에이피아이 다큐먼트를 제공하는 기능을 하는 패키지 (포스트 맨과 비슷한 기능)로 앱 실행과 함께 자동으로 실행됩니다.

에이피아이 프로젝트 설정파일 기본 패키지들

목차

• 작동원리
• 특정 컨트롤러 제외하기
• 복수 응답코드 지정하기
• 스웨거 서비스 및 미들웨어 분리하기
  • 익스텐션 클래스 생성
  • 프로그램 파일 업데이트
• 사용자 인증 추가하기

프로젝트 구성

.NET 웹 에이피아이 생성하기

작동원리

프로그램 파일에 먼저 빌더를 통해 서비스를 등록하고 앱 실행 시 에이피아이를 거쳐 반환되는 제이슨 형태의 데이터를 개발모드에서 사용 및 화면에 표시합니다 (if 조건을 제외하면 프로덕션 환경에서도 표시)

특정 컨트롤러 제외하기

컨트롤러에 경로지정 후 응답 메서드가 없는 경우

아래와 같이 에러가 뜨는 것을 방지하거나

불필요한 엔드포인트를 스웨거 UI에서 제외는 아래 옵션추가로 가능합니다

[ApiExplorerSettings(IgnoreApi = true)]

복수 응답코드 지정하기

아래와 같은 코드를 사용하여 수동으로 복수 응답코드 설정도 가능합니다.

[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]

---

※ 응답코드를 수정하는 클래스를 만든 경우 수정된 클래스를 사용하도록 아래처럼 지정가능합니다

[ProducesResponseType(typeof(CustomAPIResponse), StatusCodes.Status404NotFound)]

---

추가된 상태 코드들

스웨거 서비스 및 미들웨어 분리하기

스웨거 관련된 서비스 및 미들웨어를 Program.cs 파일에 분리하는 방법을 보겠습니다.

익스텐션 클래스 생성

익스텐션 폴더에 스웨거 익스텐션 파일을 생성

생성한 클래스를 스태틱을 바꾸고 서비스와 미들웨어를 추가하는 아래 스태틱 메서드 추가

public static IServiceCollection AddSwaggerServices(this IServiceCollection services)
{      
  return services;
}

public static IApplicationBuilder UseSwaggerMiddleware(this IApplicationBuilder app)
{      
  return app;
}

프로그램 파일에서 스웨거 관련 서비스와

미들웨어 관련 코드를 오려내고

익스텐션 클래스에 삽입

public static IServiceCollection AddSwaggerServices(this IServiceCollection services)
{
  services.AddEndpointsApiExplorer();
  services.AddSwaggerGen();
  return services;
}

public static IApplicationBuilder UseSwaggerMiddleware(this IApplicationBuilder app)
{
  app.UseSwagger();
  app.UseSwaggerUI();
  return app;
}

프로그램 파일 업데이트

Program.cs 파일에 서비스와 미들웨어를 오려낸 자리에 각 메서드 삽입

사용자 인증 추가하기

아이덴티티를 통해 사용자 인증이 추가되면 인증 어노테이션이 추가된 엔드포인트에 접근을 위해 토큰이 필요한 데 이를 위해서 설정이 필요합니다.

설정은 services.AddSwaggerGen()에 아래와 같이 옵션추가로 합니다

services.AddSwaggerGen(c =>
{
  var securitySchema = new OpenApiSecurityScheme
  {
    Description = "JWT",
    Name = "Authorization",
    In = ParameterLocation.Header,
    Type = SecuritySchemeType.Http,
    Scheme = "Bearer",
    Reference = new OpenApiReference
    {
      Type = ReferenceType.SecurityScheme,
      Id = "Bearer"
    }
  };

  c.AddSecurityDefinition("Bearer", securitySchema);

  var requirement = new OpenApiSecurityRequirement {
    {securitySchema, new[] {"Bearer"}}
  };

  c.AddSecurityRequirement(requirement);
});

설정 후 앱을 구동하면 아래와 같이 'Authorization' 버튼이 생기고

로그인 시 반환되는 토큰을 저장하면

반환되는 데이터확인이 가능합니다

이상으로 스웨거에 대해서 알아보았습니다