Asp.Net Core SwaggerUI 接入

ImLxp發表於2019-07-22
ASP.NETSwaggerUI

Asp.Net Core SwaggerUI 接入

簡單瞭解

swagger的目的簡單來說就是，不用為每個介面手動寫介面文件，因為它是根據介面自動生成的，介面更改時文件也同步更新，減少了手動更新的麻煩和遺漏。同時也提供了介面的除錯等功能，你不用開啟postman等介面測試軟體來測試介面；如果有寫備註的話，介面、入參和輸出都有詳細的備註說明，呼叫介面的人也能更加直觀的讀懂介面。溝通效率和工作效率也會大大提升。

Swagger接入的步驟：

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

一、新增Nuget包

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

二、註冊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));
});

三、新增管道

//生成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";
});

四、定義介面

  • 如果想要控制器在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 是我定義一個常量的類

相關文章