最近使用 Asp.Net Core Web Api 开发项目服务端。Swagger 是最受欢迎的 REST APIs 文档生成工具之一,进入个人视野。如下为学习应用状况的整理。html
方法1:从“程序包管理器控制台”窗口进行安装json
方法2:从“管理 NuGet 程序包”对话框中:api
(1)Startup.cs 文件中引入“using Swashbuckle.AspNetCore.Swagger;”命名空间;
(2)将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中:app
//注册Swagger生成器,定义一个和多个Swagger 文档 services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Title = "基础服务API", Version = "v1" }); });
(3)在 Startup.Configure
方法中,启用中间件生成的 JSON 文档和 Swagger UI 提供服务:asp.net
//启用中间件服务生成Swagger做为JSON终结点 app.UseSwagger(); //启用中间件服务对swagger-ui,指定Swagger JSON终结点 app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "基础服务 API V1"); });
(4)启动应用,并导航到 http://localhost:<port>/swagger/v1/swagger.json
。 生成的描述终结点的文档显示以下json格式。工具
(5)可在 http://localhost:<port>/swagger/index.html
找到 Swagger UI。 经过 Swagger UI 浏览 API文档,以下所示。学习
(6)要在应用的根 (http://localhost:<port>/
) 处提供 Swagger UI,请将 RoutePrefix
属性设置为空字符串:测试
app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "基础服务API V1"); c.RoutePrefix = string.Empty; });
一、在 AddSwaggerGen
方法的进行以下的配置操做会添加诸如做者、许可证和说明信息等:ui
//注册Swagger生成器,定义一个和多个Swagger 文档 services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Version = "v1", Title = "yilezhu's API", Description = "A simple example ASP.NET Core Web API", TermsOfService = "None", Contact = new Contact { Name = "依乐祝", Email = string.Empty, Url = "http://www.cnblogs.com/yilezhu/" }, License = new License { Name = "许可证名字", Url = "http://www.cnblogs.com/yilezhu/" } }); });
二、为接口方法添加注释spa
(1)为方法添加注释;
(2)启用XML 注释
启用 XML 注释后会为未记录的公共类型和成员提供调试信息。若是出现不少警告信息 例如,如下消息指示违反警告代码 1591:
warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'
能够按照下图所示进行取消:
注意上面生成的xml文档文件的路径:
1.对于 Linux 或非 Windows 操做系统,文件名和路径区分大小写。 例如,“SwaggerDemo.xml”文件在 Windows 上有效,但在 CentOS 上无效。
2.获取应用程序路径,建议采用Path.GetDirectoryName(typeof(Program).Assembly.Location)
这种方式或者·AppContext.BaseDirectory这样来获取
//注册Swagger生成器,定义一个和多个Swagger 文档 services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Version = "v1", Title = "yilezhu's API", Description = "A simple example ASP.NET Core Web API", TermsOfService = "None", Contact = new Contact { Name = "依乐祝", Email = string.Empty, Url = "http://www.cnblogs.com/yilezhu/" }, License = new License { Name = "许可证名字", Url = "http://www.cnblogs.com/yilezhu/" } }); // 为 Swagger JSON and UI设置xml文档注释路径 var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录(绝对,不受工做目录影响,建议采用此方法获取路径) var xmlPath = Path.Combine(basePath, "BaseAPI.xml"); c.IncludeXmlComments(xmlPath); });
经过上面的操做能够总结出,Swagger UI 显示上述注释代码的 <summary>
元素的内部文本做为api大的注释!
固然你还能够将 remarks 元素添加到 Get
操做方法文档。 它能够补充 <summary>
元素中指定的信息,并提供更可靠的 Swagger UI。 <remarks>
元素内容可包含文本、JSON 或 XML。
三、描述响应类型
接口使用者最关心的就是接口的返回内容和响应类型啦。下面展现一下201和400状态码的一个简单例子:
在咱们的方法上添加:[ProducesResponseType(201)][ProducesResponseType(400)]
而后添加相应的状态说明:返回value字符串若是id为空
/// <summary> /// 这是一个带参数的get请求 /// </summary> /// <remarks> /// 例子: /// Get api/Values/1 /// </remarks> /// <param name="id">主键</param> /// <returns>测试字符串</returns> /// <response code="201">返回value字符串</response> /// <response code="400">若是id为空</response> // GET api/values/2 [HttpGet("{id}")] [ProducesResponseType(201)] [ProducesResponseType(400)] public ActionResult<string> Get(int id) { return $"你请求的 id 是 {id}"; }
效果以下所示