.Net Core小技巧 - Swagger適配虛擬目錄及二級目錄

前言

　　隨着先後端分離模式與微服務架構的出現，Web API變得愈來愈重要及廣泛。然後出現的網關技術，使開發者更傾向於使用二級/多級目錄來暴露Web API，一是暴露的端口更少，方便管理；二是在網關中能夠處理一些公共的事務，如認證。但swagger默認是適配根（root）目錄的，想要適配二級/多級目錄，須要額外處理，同時還要區分開發環境與其它環境。一種思路是在開發環境就讓Web API是處於二級目錄，此時能夠在本機經過nginx和iis虛擬目錄來模擬，但這種思路明顯略微麻煩。另外一種思路是經過配置多環境的方式實現。

 

步驟

1. 安裝Swagger

Install-Package Swashbuckle.AspNetCore

 

2.  配置Swagger服務

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

 

3. 配置swagger中間件

var virtualPath = Configuration["virtualPath"];

app.UseSwagger(c =>
{
    c.PreSerializeFilters.Add((swaggerDoc, httpReq) => swaggerDoc.BasePath = virtualPath);
});

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint(virtualPath + "/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

 

4. 配置appsettings.json

在appsettings.json中添加virtualPath的配置：

{
  "virtualPath": "/sg", //假設二級目錄或虛擬目錄是/sg
  "Logging": {
    "IncludeScopes": false,
    "Debug": {
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "Console": {
      "LogLevel": {
        "Default": "Warning"
      }
    }
  }
}

 

在appsettings.Development.json中添加virtualPath的配置：

{
  "virtualPath": "", //使用根目錄
  "Logging": {
    "IncludeScopes": false,
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

 

測試

1. 開發環境測試

 

 

 

2. 模擬生產環境測試

修改launchSettings.json，改變環境變量參數：

 

 

準備nginx.conf，並啓動nginx。

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       80;
        server_name  localhost;

        location /sg/ {
            proxy_pass http://localhost:30925/;  
            
        }
    }
}

 

訪問二級目錄

 

小結

　　本文涉及的代碼並很少，主要想表達的是設計思路，以及對多環境的處理方案，不得不說的是，.Net Core在環境適配以及其它方面的設計都十分優秀。

　　二級目錄適配雖然是個很小的問題，可是倒是微服務實踐中一個很常見的問題。

　　二級目錄適配可否自動適配而非配置適配，也是一個值得思考的問題。　　

 

源碼

　　https://github.com/ErikXu/.NetCoreTips/tree/master/SwaggerVirtualPath