C#Swagger⽣成API接⼝说明⽂档
后端完成了接⼝之后，肯定需要告诉前端，不管是整理成 txt/excel/markdown ⽂档，亦或是写完⼀个接⼝就直接发微信告诉前端，总是要多做⼀步的事情，⽽ Swagger 则可以帮我们省去这⼀步。通过配置之后，Swagger 就可以根据我们的接⼝⾃动⽣成 API 的接⼝⽂档
Swagger 是⼀个可以将接⼝⽂档⾃动⽣成，同时可以对接⼝功能进⾏测试的开源框架，在 ASP Core 环境下，主流的有Swashbuckle.AspNetCore 和 NSwag 这两个开源框架帮助我们⽣成 Swagger documents。这⾥，我采⽤的是 。
在使⽤ Swashbuckle.AspNetCore 之前，⾸先我们需要在 API(Grapefruit.WebApi) 项⽬中添加对于 Swashbuckle.AspNetCore 的引⽤。你可以直接右键选中 API 项⽬选择管理 Nuget 程序包进⾏加载引⽤，也可以通过程序包管理控制台进⾏添加引⽤，这⾥注意，使⽤程序包管理控制台时，你需要将默认的项⽬修改成 API(Grapefruit.WebApi) 项⽬。当引⽤添加完成后，我们就可以在项⽬中配置Swagger 了。
Install-Package Swashbuckle.AspNetCore
ASP Core 的本质上可以看成是⼀个控制台程序，在我们创建好的 ASP Core Web API 项⽬中，存在着两个类⽂件：Program.cs 以及 Startup.cs。与控制台应⽤⼀样，Program 类中的 Main ⽅法是整个程序的⼊⼝，在这个⽅法中，我们将配置好的IWebHostBuilder 对象，构建成 IWebHost 对象，并运⾏该 IWebHost 对象从⽽达到运⾏ Web 项⽬的作⽤。
在框架⽣成的 Program 类⽂件中，在配置 IWebHostBuilder 的过程时，框架默认为我们添加了⼀些服务，当然，这⾥你可以注释掉默认的写法，去⾃⼰创建⼀个 WebHostBuilder 对象。同时，对于⼀个 ASP Core 程序来说，Startup 类是必须的（你可以删除⽣成的 Startup 类，重新创建⼀个新的类，但是，这个新创建的类必须包含 Configure ⽅法，之后只需要在 UStartup<Startup> 中将该类配置为 Startup 类即可），这⾥如果不指定 Startup 类会导致启动失败。
在 Startup 类中，存在着 ConfigureServices 和 Configure 这两个⽅法，在 ConfigureServices ⽅法中，我们将⾃定义服务通过依赖注⼊的⽅式添加到 IServiceCollection 容器中，⽽这些容器中的服务，最终都可以在 Configure ⽅法中进⾏使⽤；⽽ Configure ⽅法则⽤于指定 ASP Core 应⽤程序将如何响应每⼀个 HTTP 请求，我们可以在这⾥将我们⾃⼰创建的中间件（Middleware）绑定到IApplicationBuilder 上，从⽽添加到 HTTP 请求管道中。
当我们简单了解了启动过程后，就可以配置我们的 Swagger 了。Swashbuckle.AspNetCore 帮我们构建好了使⽤ Swagger 的中间件，我们只需要直接使⽤即可。
⾸先我们需要在 ConfigureServices ⽅法中，将我们的服务添加到 IServiceCollection 容器中，这⾥，我们需要为⽣成的 Swagger Document 进⾏⼀些配置。
rvices.AddSwaggerGen(s =>
{
s.SwaggerDoc("v1", new Infoanalog是什么意思
{
Contact = new Contact
{
Name = "Danvic Wang",成长的烦恼高清下载
Email = "",
Url = ""
},
Description = "A front-background project build by ASP Core 2.1 and Vue",
Title = "Grapefruit.VuCore",
Version = "v1"
});
});
之后，我们就可以在 Configure ⽅法中启⽤我们的 Swagger 中间件。
app.USwagger();
app.USwaggerUI(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. U this method to add rvices to the container.
public void ConfigureServices(IServiceCollection rvices)
olina
{
rvices.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
rvices.AddSwaggerGen(s =>
{
s.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Contact = new Microsoft.OpenApi.Models.OpenApiContact
{
Name = "dxerp",
Email = "we@dxerp",
Url = new Uri("www.dxerp")
},
Description = "A front-background project build by ASP Core 2.1 and Vue",
Title = "DXTEST.VuCore",
Version = "v1"
});
三人行必有我师翻译
//Add comments description掌上新东方
//
var baPath = System.IO.Path.GetDirectoryName(AppContext.BaDirectory);//get application located directory var baPath = System.IO.Path.GetDirectoryName(AppContext.BaDirectory);//get application located directory var apiPath = System.IO.Path.Combine(baPath, "l"); //⽣成处的XML⽂档名称
// var dtoPath = System.IO.Path.Combine(baPath, "l");
toho
s.IncludeXmlComments(apiPath, true);
// s.IncludeXmlComments(dtoPath, true);
});
}
// This method gets called by the runtime. U this method to configure the HTTP request pipeline.
气候谚语public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UDeveloperExceptionPage();
}
catalog是什么意思
el
{
app.UHsts();
}
app.USwagger();
app.USwaggerUI(s =>雅思之路
{
s.SwaggerEndpoint("/swagger/v1/swagger.json", "Grapefruit.VuCore API V1.0");
});
app.UHttpsRedirection();
app.UMvc();
}
}
