ASP.NET Web Api 2 接口API文档美化之Swagger
2015-07-28 08:56
661 查看
使用第三方提供的swgger ui 可有效提高 web api 接口列表的阅读性,并且可以在页面中测试服务接口。
但本人在查阅大量资料并进行编码测试后,发现大部分的swagger实例并不能有效运行。例如如下两个网址:http://www.cnblogs.com/caodaiming/p/4156476.html 和 http://bitoftech.net/2014/08/25/asp-net-web-api-documentation-using-swagger/。经过本人的一番折腾,最终发现,原来是由版本的差异导致的(以上两个例子在4.2.0版本下运行成功,读者可自行测试)。哎,要是这些作者能够标出插件包的版本,真能省下很多功夫。
目前Swashbuckle的最新稳定版本为5.2.1版。这个版本的编码方式与4.2.0版本有一定差异,本文也以5.2.1版本为例进行说明。
注:本文使用OWIN来自寄宿(self-host) web api,不清楚的读者可参考:http://www.asp.net/web-api/overview/hosting-aspnet-web-api/use-owin-to-self-host-web-api。
1、新建一个控制台应用程序OwinConsoleApp。Nuget分别添加Swashbuckle(5.2.1版本)和Microsoft.AspNet.WebApi.OwinSelfHost。添加Swashbuckle时,会在项目中自动添加App_Start文件夹和一个文件名为“SwaggerConfig”的文件。
2、新建一个StudentController文件, 代码如下:
3、修改SwaggerConfig文件如下:
6、右键项目属性,在属性的“生成”中设置输出文档:
注:这里的XML文件路径和文件名应与SwaggerConfig文件中的配置保持一致。
7、管理员身份运行程序。在浏览器中输入如下地址:http://localhost:9000/swagger,显示如下页面:
点击相应的服务,在显示的框中输入对应的信息,再点击“Try it out!”,即可成功调用服务,并可查看返回的结果。
后话:搞了两天,终于把swagger搞出来了,当初就是在版本的差异上浪费了太多时间。写此文章,与和我有相同经历的人共勉。文中若有纰漏,还请指出。
但本人在查阅大量资料并进行编码测试后,发现大部分的swagger实例并不能有效运行。例如如下两个网址:http://www.cnblogs.com/caodaiming/p/4156476.html 和 http://bitoftech.net/2014/08/25/asp-net-web-api-documentation-using-swagger/。经过本人的一番折腾,最终发现,原来是由版本的差异导致的(以上两个例子在4.2.0版本下运行成功,读者可自行测试)。哎,要是这些作者能够标出插件包的版本,真能省下很多功夫。
目前Swashbuckle的最新稳定版本为5.2.1版。这个版本的编码方式与4.2.0版本有一定差异,本文也以5.2.1版本为例进行说明。
注:本文使用OWIN来自寄宿(self-host) web api,不清楚的读者可参考:http://www.asp.net/web-api/overview/hosting-aspnet-web-api/use-owin-to-self-host-web-api。
1、新建一个控制台应用程序OwinConsoleApp。Nuget分别添加Swashbuckle(5.2.1版本)和Microsoft.AspNet.WebApi.OwinSelfHost。添加Swashbuckle时,会在项目中自动添加App_Start文件夹和一个文件名为“SwaggerConfig”的文件。
2、新建一个StudentController文件, 代码如下:
using System; using System.Collections.Generic; using System.Web.Http; using System.Web.Http.Description; namespace OwinConsoleApp { /// <summary> /// 学生信息 /// </summary> public class StudentController : ApiController { /// <summary> /// 得到所有的学生信息 /// </summary> /// <returns></returns> public IEnumerable<string> Get() { return new List<string>() { "student A", "student B" }; } /// <summary> /// 根据学生编号得到学生信息 /// </summary> /// <param name="Id">学生编号</param> /// <returns></returns> public string Get(int Id) { return "学号:" + Id; } /// <summary> /// 添加学生 /// </summary> /// <param name="studentModel">学生实体</param> /// <remarks>添加一个新的学生</remarks> /// <response code="400">Bad request </response> /// <response code="500">Internal Server Error</response> public void Post(String studentModel) { } /// <summary> /// 修改学生信息 /// </summary> /// <param name="Id">学生编号</param> /// <param name="studentModel">学生实体</param> [ResponseType(typeof(string))] [ActionName("UpdateStudentById")] public void Put(int Id, string studentModel) { } /// <summary> /// 删除学生信息 /// </summary> /// <param name="Id">学生编号</param> public void Delete(int Id) { } } }
3、修改SwaggerConfig文件如下:
using System.Linq; using System.Web.Http; using WebActivatorEx; using OwinConsoleApp; using Swashbuckle.Application; [assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")] namespace OwinConsoleApp { public class SwaggerConfig { public static void Register(HttpConfiguration config) { config.EnableSwagger(c => { c.SingleApiVersion("v1", ""); c.IncludeXmlComments(GetXmlCommentsPath()); c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First()); }) .EnableSwaggerUi(); } private static string GetXmlCommentsPath() { return System.String.Format(@"{0}\Swagger.XML", System.AppDomain.CurrentDomain.BaseDirectory); } } }4、新建一个Startup文件,代码如下:
using Owin; using Microsoft.Owin; using System.Web.Http; using Swashbuckle.Application; [assembly: OwinStartup(typeof(OwinConsoleApp.Startup))] namespace OwinConsoleApp { public class Startup { public void Configuration(IAppBuilder appBuilder) { // Configure Web API for self-host. HttpConfiguration config = new HttpConfiguration(); config.Routes.MapHttpRoute( name: "DefaultApi", routeTemplate: "api/{controller}/{id}", defaults: new { id = RouteParameter.Optional } ); SwaggerConfig.Register(config); appBuilder.UseWebApi(config); } } }5、修改program程序,代码如下:
using System; using Microsoft.Owin.Hosting; namespace OwinConsoleApp { class Program { static void Main(string[] args) { string baseAddress = "http://localhost:9000/"; // Start OWIN host using (WebApp.Start<Startup>(url: baseAddress)) { Console.WriteLine("OWIN SERVICE OPEN!"); Console.Read(); } Console.ReadLine(); } } }
6、右键项目属性,在属性的“生成”中设置输出文档:
注:这里的XML文件路径和文件名应与SwaggerConfig文件中的配置保持一致。
7、管理员身份运行程序。在浏览器中输入如下地址:http://localhost:9000/swagger,显示如下页面:
点击相应的服务,在显示的框中输入对应的信息,再点击“Try it out!”,即可成功调用服务,并可查看返回的结果。
后话:搞了两天,终于把swagger搞出来了,当初就是在版本的差异上浪费了太多时间。写此文章,与和我有相同经历的人共勉。文中若有纰漏,还请指出。
相关文章推荐
- ASPX和Razor
- ASP.NET MVC中如何以ajax的方式在View和Action中传递数据
- ASP.NET、HTML+CSS - 弹出提示窗体
- Asp.net-MyFirstMVCProject详细解释
- 使用PHP的CURL模拟POST采集开了viewstate的asp.net网页数据
- ASP.NET常见内置对象(一)
- 【ASP.NET】Web中的Cookie写入与读取
- [Solution] 使用 ASP.NET SignalR 添加实时 Web
- asp.net session问题
- 用asp获取服务器IP和客户端IP
- asp.net c# 打开新页面或页面跳转
- 【工作笔记0005】IIS6.0 伪静态设置,伪静态规则
- ASP.NET OWIN OAuth:遇到的2个refresh token问题
- ASP.NET MVC 使用带有短横线的html Attributes
- Web之旅第三站——ASP.NET
- Asp.net生成Excel文件并下载(更新:解决使用迅雷下载页面而不是文件的问题)
- asp.net webform download excel
- 【工作笔记0004】VS2008升级后智能提示变英文解决方法,附带汉化补丁下载
- IIS6修改ASP上传文件200K限制
- ASP.NET MVC的Razor引擎二:RazorView、RazorViewEngine