Asp Net Core Swagger自动生成接口文档

文章目录

1. Swagger是什么
2. 开始使用Swagger
3. 添加分组和注释信息
4. 总结

Swagger是什么

Swagger工具为你的Asp Net
Core生成漂亮的API文档。目前社会上大部分都是一个服务端为N个客户端提供接口，往往我们需要提供一个友好的API文档，Swagger的出现，几乎使得API文档完全自动化。

开始使用Swagger

此处我们使用开发IDE为VsCode,输入 dotnet new webapi -o SwaggerDemo 创建ASP.NET Core Web API项目
添加 Swashbuckle.AspNetCore包 （此处不讨论包的安装方法,请自行上网搜索),在.csproj文件中会生成如下引用

打开 Startup.cs 文件,添加如下代

public Startup(IConfiguration configuration, IHostingEnvironment env)
{
    Configuration = configuration;
    this.Env = env;
}
public IHostingEnvironment Env { get; }

public IConfiguration Configuration { get; }

public string[] docs = new[] { "未分类" };

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    if (Env.IsDevelopment())
    {
        services.AddSwaggerGen(options =>
        {
            foreach (var d in docs) options.SwaggerDoc(d, new Info { Version = d });
            options.DocInclusionPredicate((docName, description) =>
            {
                description.TryGetMethodInfo(out MethodInfo mi);
                var attr = mi.DeclaringType.GetCustomAttribute<ApiExplorerSettingsAttribute>();
                if (attr != null)
                {
                    return attr.GroupName == docName;
                }
                else
                {
                    return docName == "未分类";
                }
            });
            var ss = options.SwaggerGeneratorOptions;
            options.IncludeXmlComments(@"E:\VsCode\C#\.Net Core\第三章 利用Swagger生成接口文档\SwaggerDemo\bin\Debug\netcoreapp2.2\SwaggerDemo.xml");
        });
    }
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseMvc();
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseSwagger()
        .UseSwaggerUI(options  =>
        {
            options.DocumentTitle = "Ron.liang Swagger 测试文档";
            foreach (var item in docs)
                options.SwaggerEndpoint($"/swagger/{item}/swagger.json", item);
        });
    }
}