Asp.Net Core SwaggerUI 接入

Asp.Net Core SwaggerUI 接入

簡單瞭解

swagger的目的簡單來講就是，不用爲每一個接口手動寫接口文檔，由於它是根據接口自動生成的，接口更改時文檔也同步更新，減小了手動更新的麻煩和遺漏。同時也提供了接口的調試等功能，你不用打開postman等接口測試軟件來測試接口；若是有寫備註的話，接口、入參和輸出都有詳細的備註說明，調用接口的人也能更加直觀的讀懂接口。溝通效率和工做效率也會大大提高。

Swagger接入的步驟：

1. 註冊Swagger生成器：services.AddSwaggerGen().
2. 插入中間件，將生成的Swagger公開爲JSON節點：app.UseSwagger()
3. 插入Swagger-UI中間件，將指定的swagger json端點爲其提供支持：app.UseSwaggerUI()

1、添加Nuget包

Package Manager : Install-Package Swashbuckle.AspNetCore
或
CLI : dotnet add package Swashbuckle.AspNetCore

2、註冊swagger文檔服務

• 注意

1. 若是mvc使用的是services.AddMvcCore()，則須要手動添加ApiExplorer,由於SwashBuckle強烈依賴於ApiExplorer,ApiExplorer用來發現控制器中的接口方法。須要手動添加。如：
   services.AddMvcCore().AddApiExplorer();

2. 若是使用的是services.AddMvc()，則不須要再進行註冊。由於AddMvc()中已經添加了ApiExplorer。如：

   public static IMvcBuilder AddMvc(this IServiceCollection services)
       {
           if (services == null)
               throw new ArgumentNullException(nameof (services));
           IMvcCoreBuilder builder = services.AddMvcCore();
           builder.AddApiExplorer();//在這裏
           builder.AddAuthorization();
           MvcServiceCollectionExtensions.AddDefaultFrameworkParts(builder.PartManager);
           builder.AddFormatterMappings();
           builder.AddViews();
           builder.AddRazorViewEngine();
           builder.AddRazorPages();
           builder.AddCacheTagHelper();
           builder.AddDataAnnotations();
           builder.AddJsonFormatters();
           builder.AddCors();
           return (IMvcBuilder) new MvcBuilder(builder.Services, builder.PartManager);
       }

3. 何時用AddMvc()，何時用AddMvcCore()呢？
   經過AddMvc()的方法中咱們應該能夠發現，裏面有添加View、Razor和TagHelper服務，這些在WebApi項目中是用不到的。因此：
   1).若是你的項目是mvc web程序，則使用AddMvc().
   2).若是的項目是webapi,則使用AddMvcCore(),而後酌情添加須要的其它服務；固然使用AddMvc()也沒有問題。

• 添加Swagger服務

services.AddSwaggerGen(options =>
{
    options.SwaggerDoc(AppDefaults.ApiDocumentName, new Info
    {
        Title = AppDefaults.ApiDocumentTitle,
        Description = AppDefaults.ApiDocumentDescription,
        Version = typeof(Startup).Assembly.GetName().Version.ToString()
    });
    //加載註釋文件
    Directory.GetFiles(Environment.ContentRootPath, "*.xml", SearchOption.AllDirectories)
        .ToList()
        .ForEach(f => options.IncludeXmlComments(f));
});

3、添加管道

//生成swagger-json文件，並重定義swagger-json文件路由模板,這裏我修改了 swagger-json 的路由模板。
//若是不自定義的話，默認是 swagger/{documentName}/swagger.json
app.UseSwagger(options => options.RouteTemplate = "{documentName}/swagger.json");

app.UseSwaggerUI(options =>
{
    //指定生成swagger-json文件路徑，爲SwaggerUI提供數據。
    //若是上邊路由模板沒有自定義，則完成路徑是 /swagger/{AppDefaults.ApiDocumentName}/swagger.json
    options.SwaggerEndpoint($"/{AppDefaults.ApiDocumentName}/swagger.json", AppDefaults.ApiDocumentName);

    //自定義SwaggerUI頁面路由前綴
    //地址欄輸入 http://loacalhost:5000/lxp  就能夠打開SwaggerUI頁面
    options.RoutePrefix = "lxp";
});

4、定義接口

• 若是想要控制器在Swagger中顯示，全部控制器必須使用屬性路由
• 接口方法要使用 Http 屬性和 From 特性標註

例如：

[Route("[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        [HttpGet("name")]
        public async Task<ActionResult<string>> GetNameAsync([FromQuery] string name)
        {
            if (!string.IsNullOrEmpty(name))
            {
                ModelState.TryAddModelError(nameof(name), $"{nameof(name)} can not be empty");
            }

            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }

            return await Task.FromResult(name);
        }
    }

補充:

• AppDefaults 是我定義一個常量的類