什么是Swagger?
说swagger 之前，我们先说一下OpenApi 规范。
OpenApi 是一种和语言无关的用于描述RESTAPIs 接口功能的一种规范，对RESTAPIs 接口的描述包括： 接口参数信息、接口返回值信息、api 功能描述、请求路径等。
这里我们说OpenApi 只是一种规范，既然是一种规范，就必然有相应的实现，Swagger 就是其中一个实现了Open Api 规范的工具。
.net 中RESTAPIs的代表便是 web api ，并且.net 针对Web Api 也有相应的Swagger 实现，主要有：Swashbuckle 和 NSwag，本文主要讲解如何通过 Swashbuckle库 将SwaggerUI集成到asp.net core项目中去，并快速生成asp.net web api 接口文档。
基本原理分析在开始进入正题前，我们先看下我的 web api 示例站点中快速集成swagger ui 后的效果，并记住下面提到的 SwaggerUI 界面 和 OpenApi Json 信息 两个关键词，因为后面会多次提到这两个词语。
SwaggerUI 界面如下图：
OpenApi Json 信息如下（该Json信息描述了web api 所有接口，按照OpenApi规范生成）：
大致的原理就是，当我们浏览器中输入：:5000/swagger/index.html 请求SwaggerUI 页面，SwaggerUI 中间件拦截到这个请求后，读取内置SwaggerUI 页面内容并响应给浏览器,浏览器再发起一个异步请求去请求OpenApi Json 信息，然后根据OpenApi Json 信息生成上面第一张图中所有的接口信息，我们可以通过浏览器的开发人员工具看到这个请求。
OK，了解完SwaggerUI 的基本原理后，下面我们来讲解如何快速将SwaggerUI 集成到 Web Api 项目中去。
安装swagger相关nuget包在需要集成swagger的项目中安装nuget 包：Swashbuckle.AspNetCore
注入SwaggerAPI文档生成服务，添加SwaggerUI 响应中间件
打开SwaggerDemo下的Startup.cs文件，修改Configuservice 方法，将API文档生成服务添加到依赖注入容器中。
public void ConfigureServices(IServiceCollection services) { //这里将OpenApi Json 信息生成服务添加到依赖注入容器中，负责根据web api 的定义生成相应的OpenApi Json 信息。 services.AddSwaggerGen(); services.AddControllersWithViews(); }
修改Startup.cs 下的 Configure 方法，将Swagger UI 请求拦截中间件、OpenApi Json 信息请求拦截中间件加入到请求中间件管道列表中去。
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } else { app.UseExceptionHandler("/Home/Error"); } app.UseStaticFiles(); //UseSwagger添加了一个中间件，这个中间件主要是拦截 浏览器中发送过来的 获取OpenApi Json 信息的HTTP请求，并把WebApi 描述信息返回给SwaggerUI，上图中，我么可以看到默认请求OpenApi Json 信息的http地址是：:5000/swagger/v1/swagger.json app.UseSwagger(); //UseSwaggerUI 添加了一个中间件，主要用于拦截SwaggerUI界面的访问请求，并根据OpenApi Json 信息动态生成接口列表，在上面的基本原理讲述中，默认请求SwaggerUI 界面的http地址是：:5000/swagger/index.html app.UseSwaggerUI((options) => { //SwaggerEndPoint 方法用于告诉SwaggerUI 请求哪个地址来获取OpenApi Json 信息，后面我们会讲解如何自定义这个路径。 options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); }); app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllerRoute( name: "default", pattern: "{controller=Home}/{action=Index}/{id?}"); }); }
OK，至此，SwaggerUI 就已经集成到了我们的WebApi 项目中去了，如果不出意外，那么可以正常看到我上面 基本原理分析中提到的效果图了，是不是很简单，下面我们来讲解一些更深入一些的用法。
如何自定义OpenApi Json 信息请求Http地址?默认OpenApi Json 信息的请求地址为：/swagger/v1/swagger.json,如果我们想换成其他地址，比如改成：/BlogApis/v1/swagger.json 该如何操作呢？
首先配置拦截SwaggerUI界面请求的中间件，告诉SwaggerUI 从哪个地址去请求获取 OpenApi Json 信息。
app.UseSwaggerUI((options) => { //options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); //这里告诉SwaggerUI从/BogApis/v1/swagger.json 获取 OpenApi Json 信息。 options.SwaggerEndpoint("/BlogApis/v1/swagger.json", "BlogApis"); });
然后配置拦截OpenAPI Json 信息的中间件，重新定义OpenApi Json信息的请求路径格式，如下：