Asp.Net Core WebAPI 가 Swagger 를 사용 할 때 API 숨 김 및 그룹 상세 설명

1.머리말
왜 우 리 는 부분 인 터 페 이 스 를 숨겨 야 합 니까?
우리 가 인 터 페 이 스 를 swagger 로 대체 할 때 일부 인 터 페 이 스 는 직관 적 으로 노출 되 는 것 을 피하 기 어렵다.예 를 들 어 우리 가 Consul 과 결합 하여 사용 할 때 건강 검사 인터페이스 와 경보 알림 인 터 페 이 스 를 노출 시 킬 수 있다.이런 인 터 페 이 스 는 가끔 편리 한 고려 에서 암호 화 되 지 않 았 을 때 우 리 는 인 터 페 이 스 를 숨겨 야 한다.내부 개발 자만 알 고 있 습 니 다.
왜 팀 을 나 눠 요?
보통 앞 뒤 가 분 리 된 항목 을 쓸 때 전단 페이지 를 호출 할 수 있 도록 많은 인 터 페 이 스 를 만 날 수 있 습 니 다.인터페이스 가 수백 개 에 이 르 렀 을 때 프레임 인터페이스 가 무엇 인지,업무 인터페이스 가 무엇 인지 구분 해 야 합 니 다.이 럴 때 swaggerUI 의 인터페이스 에 그룹 을 나 누 는 것 이 좋 은 선택 입 니 다.

swagger 의 기본 사용 여 기 는 더 이상 군말 하지 않 고 읽 을 수 있 습 니 다마이크로소프트 공식 문서.기본적으로 사용 할 수 있 습 니 다.
2.swaggerUI 에 인증 요청 추가
새 HttpHeader OperationFilter 작업 필터,계승Swashbuckle.AspNetCore.SwaggerGen.IOperationFilter인터페이스,적용 방법

/// <summary>
/// swagger   
/// </summary>
public class HttpHeaderOperationFilter : IOperationFilter
{
 public void Apply(Operation operation, OperationFilterContext context)
 {
  #region    
  if (operation.Parameters == null)
  {
   operation.Parameters = new List<IParameter>();
  }

  if (context.ApiDescription.TryGetMethodInfo(out MethodInfo methodInfo))
  {
   if (!methodInfo.CustomAttributes.Any(t => t.AttributeType == typeof(AllowAnonymousAttribute))
     &&!(methodInfo.ReflectedType.CustomAttributes.Any(t => t.AttributeType == typeof(AuthorizeAttribute))))
   {
    operation.Parameters.Add(new NonBodyParameter
    {
     Name = "Authorization",
     In = "header",
     Type = "string",
     Required = true,
     Description = "   Token，   bearer XXX"
    });
   }
  }
  #endregion

  #region    
  //if (operation.Parameters == null)
  //{
  // operation.Parameters = new List<IParameter>();
  //}
  //var actionAttrs = context.ApiDescription.ActionAttributes().ToList();
  //var isAuthorized = actionAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));
  //if (isAuthorized == false)
  //{
  // var controllerAttrs = context.ApiDescription.ControllerAttributes();
  // isAuthorized = controllerAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));
  //}
  //var isAllowAnonymous = actionAttrs.Any(a => a.GetType() == typeof(AllowAnonymousAttribute));
  //if (isAuthorized && isAllowAnonymous == false)
  //{
  // operation.Parameters.Add(new NonBodyParameter
  // {
  //  Name = "Authorization",
  //  In = "header",
  //  Type = "string",
  //  Required = true,
  //  Description = "   Token，   bearer XXX"
  // });
  //}
  #endregion
 }
}

그리고 Startup.cs 의 Configure Services 방법 을 수정 하고 사용자 정의 HttpHeader OperationFilter 필 터 를 추가 합 니 다.

public IServiceProvider ConfigureServices(IServiceCollection services)
{
 ...
 services.AddSwaggerGen(c =>
 {
  ...
  c.OperationFilter<HttpHeaderOperationFilter>();
 });
 ...
}

이 럴 때 저희 가 swaggerUI 를 다시 방문 하면 Token 을 입력 할 수 있 습 니 다.

3.API 그룹
Startup.cs 의 Configure Services 방법 을 수정 하고 여러 swagger 문 서 를 추가 합 니 다.

public IServiceProvider ConfigureServices(IServiceCollection services)
{
 ...
 services.AddSwaggerGen(c =>
 {
  c.SwaggerDoc("v1", new Info
  {
   Version = "v1",
   Title = "    ",
   Description = "    -  ",
   TermsOfService = "",
   Contact = new Contact
   {
    Name = "XXX1111",
    Email = "[email protected]",
    Url = ""
   }
  });

  c.SwaggerDoc("v2", new Info
  {
   Version = "v2",
   Title = "    ",
   Description = "    -  ",
   TermsOfService = "",
   Contact = new Contact
   {
    Name = "XXX2222",
    Email = "[email protected]",
    Url = ""
   }
  });

  //           
  GetAllAssemblies().Where(t => t.CodeBase.EndsWith("Controller.dll")).ToList().ForEach(assembly =>
   {
    c.IncludeXmlComments(assembly.CodeBase.Replace(".dll", ".xml"));
   });

  c.OperationFilter<HttpHeaderOperationFilter>();
  //c.DocumentFilter<HiddenApiFilter>();
 });
 ...
}

Startup.cs 의 Configure 방법 을 수정 하여 가입 합 니 다.

public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
 ...
 app.UseSwagger();
 app.UseSwaggerUI(c =>
 {
  c.SwaggerEndpoint("/swagger/v2/swagger.json", "    -  ");//          
  c.SwaggerEndpoint("/swagger/v1/swagger.json", "    -  ");//            
  c.RoutePrefix = string.Empty;//       IP         
 });
 ...

}

그리고 저희 컨트롤 러 에 swagger 문서 버 전 을 표시 해 야 합 니 다.

이때 우 리 는 인터페이스 문 서 를 그룹 으로 나 누 어 표시 할 수 있다.

4.API 숨 김
사용자 정의 숨 김 기능 만 들 기 HiddenapiAttribute.cs

/// <summary>
///   swagger      
/// </summary>
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class HiddenApiAttribute:System.Attribute
{
}

API 숨 김 필터 HiddenApiFilter 계승Swashbuckle.AspNetCore.SwaggerGen.IDocumentFilter인 터 페 이 스 를 만 들 고 적용 방법

/// <summary>
///    Swagger     
/// </summary>
public class HiddenApiFilter : IDocumentFilter
{
 public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
 {
  foreach (ApiDescription apiDescription in context.ApiDescriptions)
  {
   if (apiDescription.TryGetMethodInfo(out MethodInfo method))
   {
    if (method.ReflectedType.CustomAttributes.Any(t=>t.AttributeType==typeof(HiddenApiAttribute))
      || method.CustomAttributes.Any(t => t.AttributeType == typeof(HiddenApiAttribute)))
    {
     string key = "/" + apiDescription.RelativePath;
     if (key.Contains("?"))
     {
      int idx = key.IndexOf("?", System.StringComparison.Ordinal);
      key = key.Substring(0, idx);
     }
     swaggerDoc.Paths.Remove(key);
    }
   }
  }
 }
}

Startup.cs 에서 HiddenapiFilter 사용 하기

public IServiceProvider ConfigureServices(IServiceCollection services)
{
 ...
 services.AddSwaggerGen(c =>
 {
  c.SwaggerDoc("v1", new Info
  {
   Version = "v1",
   Title = "    ",
   Description = "    -  ",
   TermsOfService = "",
   Contact = new Contact
   {
    Name = "XXX1111",
    Email = "[email protected]",
    Url = ""
   }
  });

  c.SwaggerDoc("v2", new Info
  {
   Version = "v2",
   Title = "    ",
   Description = "    -  ",
   TermsOfService = "",
   Contact = new Contact
   {
    Name = "XXX2222",
    Email = "[email protected]",
    Url = ""
   }
  });

  //           
  GetAllAssemblies().Where(t => t.CodeBase.EndsWith("Controller.dll")
   && !t.CodeBase.Contains("Common.Controller.dll")).ToList().ForEach(assembly =>
   {
    c.IncludeXmlComments(assembly.CodeBase.Replace(".dll", ".xml"));
   });

  c.OperationFilter<HttpHeaderOperationFilter>();
  c.DocumentFilter<HiddenApiFilter>();
 });
 ...
}

예시:
저 는 Consul 의 심장 박동 검사 인 터 페 이 스 를 제공 합 니 다.

인터페이스 문서 에 표시 되 지 않 았 습 니 다.

총결산
이상 은 이 글 의 모든 내용 입 니 다.본 고의 내용 이 여러분 의 학습 이나 업무 에 어느 정도 참고 학습 가 치 를 가지 기 를 바 랍 니 다.여러분 의 저희 에 대한 지지 에 감 사 드 립 니 다.