C# Swagger 生成API接口说明文档

后端完成了接口之后，肯定需要告诉前端，不管是整理成 txt/excel/markdown 文档，亦或是写完一个接口就直接发微信告诉前端，总是要多做一步的事情，而 Swagger 则可以帮我们省去这一步。通过配置之后，Swagger 就可以根据我们的接口自动生成 API 的接口文档

　　Swagger 是一个可以将接口文档自动生成，同时可以对接口功能进行测试的开源框架，在 ASP.NET Core 环境下，主流的有 Swashbuckle.AspNetCore 和 NSwag 这两个开源框架帮助我们生成 Swagger documents。这里，我采用的是 Swashbuckle.AspNetCore。

　　在使用 Swashbuckle.AspNetCore 之前，首先我们需要在 API(Grapefruit.WebApi) 项目中添加对于 Swashbuckle.AspNetCore 的引用。你可以直接右键选中 API 项目选择管理 Nuget 程序包进行加载引用，也可以通过程序包管理控制台进行添加引用，这里注意，使用程序包管理控制台时，你需要将默认的项目修改成 API(Grapefruit.WebApi) 项目。当引用添加完成后，我们就可以在项目中配置 Swagger 了。

Install-Package Swashbuckle.AspNetCore

ASP.NET Core 的本质上可以看成是一个控制台程序，在我们创建好的 ASP.NET Core Web API 项目中，存在着两个类文件：Program.cs 以及 Startup.cs。与控制台应用一样，Program 类中的 Main 方法是整个程序的入口，在这个方法中，我们将配置好的 IWebHostBuilder 对象，构建成 IWebHost 对象，并运行该 IWebHost 对象从而达到运行 Web 项目的作用。

　　在框架生成的 Program 类文件中，在配置 IWebHostBuilder 的过程时，框架默认为我们添加了一些服务，当然，这里你可以注释掉默认的写法，去自己创建一个 WebHostBuilder 对象。同时，对于一个 ASP.NET Core 程序来说，Startup 类是必须的（你可以删除生成的 Startup 类，重新创建一个新的类，但是，这个新创建的类必须包含 Configure 方法，之后只需要在 UseStartup 中将该类配置为 Startup 类即可），这里如果不指定 Startup 类会导致启动失败。

　　在 Startup 类中，存在着 ConfigureServices 和 Configure 这两个方法，在 ConfigureServices 方法中，我们将自定义服务通过依赖注入的方式添加到 IServiceCollection 容器中，而这些容器中的服务，最终都可以在 Configure 方法中进行使用；而 Configure 方法则用于指定 ASP.NET Core 应用程序将如何响应每一个 HTTP 请求，我们可以在这里将我们自己创建的中间件（Middleware）绑定到 IApplicationBuilder 上，从而添加到 HTTP 请求管道中。

　　当我们简单了解了启动过程后，就可以配置我们的 Swagger 了。Swashbuckle.AspNetCore 帮我们构建好了使用 Swagger 的中间件，我们只需要直接使用即可。

　　首先我们需要在 ConfigureServices 方法中，将我们的服务添加到 IServiceCollection 容器中，这里，我们需要为生成的 Swagger Document 进行一些配置。

services.AddSwaggerGen(s =>
{
    s.SwaggerDoc("v1", new Info
    {
        Contact = new Contact
        {
            Name = "Danvic Wang",
            Email = "[email protected]",
            Url = "https://yuiter.com"
        },
        Description = "A front-background project build by ASP.NET Core 2.1 and Vue",
        Title = "Grapefruit.VuCore",
        Version = "v1"
    });
});

　　之后，我们就可以在 Configure 方法中启用我们的 Swagger 中间件。

app.UseSwagger();
app.UseSwaggerUI(s =>
{
    s.SwaggerEndpoint("/swagger/v1/swagger.json", "Grapefruit.VuCore API V1.0");
});

　　此时，当你运行程序，在域名后面输入/swagger 即可访问到我们的 API 文档页面。因为项目启动时默认访问的是我们 api/values 的 GET 请求接口，这里我们可以打开 Properties 下的 launchSetting.json 文件去配置我们的程序默认打开页面。

　　从上面的图可以看出，不管是使用 IIS 或是程序自托管，我们默认打开的 Url 都是 api/values，这里我们将两种启动方式的 launchUrl 值都修改成 swagger 之后再次运行我们的项目，可以发现，程序默认的打开页面就会变成我们的 API 文档页面。不管是使用 IIS 或是程序自托管，我们默认打开的 Url 都是 api/values，这里我们将两种启动方式的 launchUrl 值都修改成 swagger 之后再次运行我们的项目，可以发现，程序默认的打开页面就会变成我们的 API 文档页面。

 

 

我们使用 API 文档的目的，就是为了让前端知道请求的方法地址是什么，需要传递什么参数，而现在，并没有办法显示出我们对于参数以及方法的注释，通过查看 Swashbuckle.AspNetCore 的 github 首页可以看到，我们可以通过配置，将生成的 json 文件中包含我们对于 Controller or Action 的 Xml 注释内容，从而达到显示注释信息的功能（最终呈现的 Swagger Doc 是根据之前我们定义的这个 “/swagger/v1/swagger.json” json 文件来生成的）。

　　右键我们的 API 项目，属性 =》生产，勾选上 XML 文档文件，系统会默认帮我们创建生成 XML 文件的地址，这时候，我们重新生成项目，则会发现，当前项目下会多出这个 XML 文件。在重新生成项目的过程中，你会发现，错误列表会显示很多警告信息，提示我们一些方法没有添加 XML 注释。如果你和我一样强迫症的话，可以把 1591 这个错误添加到上面的禁止显示警告中，这样就可以不再显示这个警告了。

创建好 XML 的注释文件后，我们就可以配置我们的 Swagger 文档，从而达到显示注释的功能。这里，因为我会在 Grapefruit.Application 类库中创建各种的 Dto 对象，而接口中是会调用到这些 Dto 对象的。因此，为了显示这些 Dto 上的注释信息，这里我们也需要生成 Grapefruit.Application 项目的 XML 注释文件。

　　PS：这里我是将每个项目生成的注释信息 xml 文档地址都放在了程序的基础路径下，如果你将 xml 文档生成在别的位置，这里获取 xml 的方法就需要你进行修改。

 public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // 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_1);

            services.AddSwaggerGen(s =>
            {
                s.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
                {
                    Contact = new Microsoft.OpenApi.Models.OpenApiContact
                    {
                        Name = "dxerp",
                        Email = "[email protected]",
                        Url = new Uri("http://www.dxerp.net")
                    },
                    Description = "A front-background project build by ASP.NET Core 2.1 and Vue",
                    Title = "DXTEST.VuCore",
                    Version = "v1"
                });
                //Add comments description
                //
                var basePath = System.IO.Path.GetDirectoryName(AppContext.BaseDirectory);//get application located directory
               var basePath = System.IO.Path.GetDirectoryName(AppContext.BaseDirectory);//get application located directory
                var apiPath = System.IO.Path.Combine(basePath, "AspCoreTest.xml"); //生成处的XML文档名称
               // var dtoPath = System.IO.Path.Combine(basePath, "Grapefruit.Application.xml");
                s.IncludeXmlComments(apiPath, true);
               // s.IncludeXmlComments(dtoPath, true);

            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseHsts();
            }
            app.UseSwagger();
            app.UseSwaggerUI(s =>
            {
                s.SwaggerEndpoint("/swagger/v1/swagger.json", "Grapefruit.VuCore API V1.0");
            });

            app.UseHttpsRedirection();
            app.UseMvc();
        }
    }

 

　　当我们把 Swagger 配置完成之后，我们就可以创建具有版本控制的 API 接口了。