.NET Core使用swagger进行API接口文档管理详细操作步骤（二）

在框架中加入 Swagger  并发布  到 IIS （1）首先点击依赖项》管理Nuget包 （2）输入 Swashbuckle.aspnetCore  比如： 图中两个Swagger 插件需要我们安装   注意：我这里已经安装过显示的是 卸载  （3） 在框架中 添加Swagger 注解的帮助类   HttpHeaderOperation  下面是我完整的.CS文件 using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; //添加引用 using Swashbuckle.AspNetCore.Swagger; using Swashbuckle.AspNetCore.SwaggerGen; using Microsoft.AspNetCore.Authorization; namespace WebCoreApi { public class HttpHeaderOperation : IOperationFilter { /// <summary> /// 实现接口 /// </summary> /// <param name="operation"></param> /// <param name="context"></param> public void Apply(Operation operation, OperationFilterContext context) { if (operation.Parameters == null) { operation.Parameters = new List<IParameter>(); } var actionAttrs = context.ApiDescription.ActionAttributes(); var isAuthorized = actionAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute)); if (isAuthorized == false) //提供action都没有权限特性标记，检查控制器有没有 { var controllerAttrs = context.ApiDescription.ControllerAttributes(); isAuthorized = controllerAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute)); } var isAllowAnonymous = actionAttrs.Any(a => a.GetType() == typeof(AllowAnonymousAttribute)); if (isAuthorized && isAllowAnonymous == false) { operation.Parameters.Add(new NonBodyParameter() { Name = "Authorization", //添加Authorization头部参数 In = "header", Type = "string", Required = false }); } } } } （4） 添加 Swagger 的·服务方法 在  Startup中的  ConfigureServices方法里 public void ConfigureServices(IServiceCollection services) { services.AddMvc(); services.AddSwaggerGen(x => { x.SwaggerDoc("v1", new Info { Version = "v1", //版本号 Title = "Szl接口文档", //标题 Description = "RESTful API ", TermsOfService = "",//服务的条件 //第一个参数Name 创建人名称/也可以是 负责人名称 第二个参数 联系邮箱 Contact = new Contact { Name = "Su", Email = "[email protected]", Url = "北京" } }); //获取设置配置信息的 的路径对象 swagger界面配置 var basePath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(basePath, "AspNetCoreApiSwagger.xml"); x.IncludeXmlComments(xmlPath); x.OperationFilter<HttpHeaderOperation>(); // 添加httpHeader参数 }); } （5）添加 Swagger 启动项 在  Startup中的  Configure方法里 public void Configure(IApplicationBuilder app, IHostingEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseMvc(); app.UseSwagger(); // 指定站点 app.UseSwaggerUI(x => { //做出一个限制信息 描述 x.SwaggerEndpoint("/swagger/v1/swagger.json", "TwBusManagement API V1"); //显示在发出请求时发送的标题 x.ShowRequestHeaders(); }); } （6） 在框架自动生成的 Api 控制器里Post的方法上加入 注解（其他方法也可以，我只是举例） /// <summary> /// AspNet Core Post请求 /// </summary> /// <param name="value">User类</param> /// <remarks> ///访问参数 /// POST /// { /// "value": "0e7ad584-7788-4ab1-95a6-ca0a5b444cbb", /// } /// /// </remarks> /// <response code="201">返回新创建项</response> /// <response code="400">如果为空时</response> [HttpPost] [ProducesResponseType(typeof(User), 201)] [ProducesResponseType(typeof(User), 400)] public void Post([FromBody]User value) { } 注解的含义如下 summary 用来描述 方法的作用 remarks 用来描述传入的参数格式/也可以把调用的值放入里面 response 定义两个返回状态 User 类 /// <summary> /// 用户类 /// </summary> public class User { /// <summary> /// 用户ID /// </summary> public int UserID { get; set; } /// <summary> /// 用户名称 /// </summary> public int UserName { get; set; } /// <summary> /// 用户年龄 /// </summary> public int UserAge { get; set; } } （7）在框架中   添加 AspNetCoreApiSwagger.xml 文件  一定要注意的是  xml 文件必须定义一个根节点 不然会报错  ，XML的属性   改为 始终复制   （XML文件在 第四步骤中有用到） （8）设置 项目的生成 输出路径 （9）  发布   以文件夹发布就行 （10）部署IIS 说一下注意点     改成无托管代码 （11）打开IIS服务  中的模块     （12）查看是否有  AspNetCoreModule  没有进行安装 我是在国外的网站下载的   （13）  如果在运行部署的API  发生了错误 我们在  Program  中加入  如代码所示  可以帮助我们准确定义的问题所在 public class Program { public static void Main(string[] args) { BuildWebHost(args).Run(); } public static IWebHost BuildWebHost(string[] args) => WebHost.CreateDefaultBuilder(args) //发布程序出现错误帮助定位详细错误信息 // .UseKestrel() //.UseContentRoot(Directory.GetCurrentDirectory()) //.UseSetting("detailedErrors", "true") //.UseIISIntegration() .CaptureStartupErrors(true) .UseStartup<Startup>() .Build(); }   OK  今天就完成了，   以后会描述一下 框架的基础知识  比如  应用程序的启动、日子、路由、静态文件、WebSockteS  等， 等到基础描述过后，在框架中加入一些我闷在实战中用到的，希望大家多多指出错误不足之处，这是我的学习。   补充一下显示结果，开始的时候忘记截图了     有人在实践中遇到了没有注释的问题 在启动的时候  注意这里 XML名称是否错误 代码中读取的注释信息在 AspNetCoreApiSwagger.xml中，项目启动后会把注释信息生成到AspNetCoreApiSwagger.xml中  .