查看: 165|回复: 0

[.NET源码] WebApi使用swagger ui自动生成接口文档

发表于 5 天前
太阳http代理AD

之前就写到。最近正在使用webapi。这里介绍一个实用的东西swageer ui
现在开发都是前后端分开。我们这里是给前端提供api。有时候对于一个api的描述,并不想专门写一份文档。很浪费时间。
swagger ui就是一个能整合到项目中让api的注释能够生成到一个网页上。能简单测试和给前端看。
开怼吧。

Step.1 Nuget安装
打开你的Nuget console,Install-Package Swashbuckle(要选择哪个项目)

ps.其实第一步安装完了,你什么不用做。运行起来,网址进入/swagger/ui/index就能看到你的那些api了(不带注释),不过没达到我们的预期效果——将注释自动生成到文档上。so,继续往下看

Step.2 加上生成注释的代码
安装之后会在App_Start文件夹中多了SwaggerConfig.cs类,该类中的Register()方法会在应用程序启动的时候调用
里面好多注释,绿绿的,还是选择原谅他,删掉吧,删掉后就这剩下这些

  1. 1 public static void Register()
  2. 2 {
  3. 3   var thisAssembly = typeof(SwaggerConfig).Assembly;
  4. 4
  5. 5   GlobalConfiguration.Configuration
  6. 6   .EnableSwagger(c =>
  7. 7   {
  8. 8     c.SingleApiVersion("v1", "WebApplication1");
  9. 9   })
  10. 10   .EnableSwaggerUi(c =>
  11. 11   {
  12. 12
  13. 13   });
  14. 14 }
复制代码

稍微改造一下,附加个注释xml上去

  1. 1 public static void Register()
  2. 2 {
  3. 3 var thisAssembly = typeof(SwaggerConfig).Assembly;
  4. 4
  5. 5 GlobalConfiguration.Configuration
  6. 6 .EnableSwagger(c =>
  7. 7 {
  8. 8 c.SingleApiVersion("v1", "WebApplication1");
  9. 9 c.IncludeXmlComments(GetXmlCommentsPath());
  10. 10 })
  11. 11 .EnableSwaggerUi(c =>
  12. 12 {
  13. 13
  14. 14 });
  15. 15 }
  16. 16 private static string GetXmlCommentsPath()
  17. 17 {
  18. 18 return System.String.Format(@"{0}\bin\WebApplication1.XML", System.AppDomain.CurrentDomain.BaseDirectory);
  19. 19 }
复制代码

Step.3 步骤2所必须的
启用生成xml文档,右击项目文件属性 bulid发布——Output输出(勾选XML文件)

其实swagger他就是依赖于build时生成的这个xml来自动生成注释上页面的

Step.4 完成啦,看看页面



当然,我的追求不止这些,我们来优化优化
首先,我比较喜欢将config都弄进WebApiConfig中就好,看起来比较清晰

  1. 1 public static class WebApiConfig
  2. 2 {
  3. 3 public static void Register(HttpConfiguration config)
  4. 4 {
  5. 5 // Web API configuration and services
  6. 6
  7. 7 // Web API routes
  8. 8 config.MapHttpAttributeRoutes();
  9. 9
  10. 10 config.Routes.MapHttpRoute(
  11. 11 name: "DefaultApi",
  12. 12 routeTemplate: "api/{controller}/{id}",
  13. 13 defaults: new { id = RouteParameter.Optional }
  14. 14 );
  15. 15
  16. 16 config.RegistSwagger();//添加这个swagger的Regist
  17. 17 }
  18. 18 private static void RegistSwagger(this HttpConfiguration config)
  19. 19 {
  20. 20 config.EnableSwagger("docs/{apiVersion}/swagger", c =>
  21. 21 {
  22. 22 c.SingleApiVersion("v1", "WebApplication1");
  23. 23 c.IncludeXmlComments(GetXmlCommentsPath());
  24. 24 })
  25. 25 .EnableSwaggerUi(c=>
  26. 26 {
  27. 27
  28. 28 });
  29. 29 }
  30. 30 private static string GetXmlCommentsPath()
  31. 31 {
  32. 32 return $@"{AppDomain.CurrentDomain.RelativeSearchPath}\WebApplication1.XML";
  33. 33 }
  34. 34 }
复制代码

这个swagger的路径也配一下吧,可以自定义一下

  1. 1 private static void RegistSwagger(this HttpConfiguration config)
  2. 2 {
  3. 3 config.EnableSwagger("docs/{apiVersion}/swagger", c =>
  4. 4 {
  5. 5 c.SingleApiVersion("v1", "WebApplication1");
  6. 6 c.IncludeXmlComments(GetXmlCommentsPath());
  7. 7 })
  8. 8 .EnableSwaggerUi("apis/{*assetPath}");//原本进入的地址是/swagger/ui/index 这样就能换地址成/apis/index
  9. 9 }
复制代码

这样,我们这基本的配置就可以了,实现预期的效果——自动生成接口文档
这里面的配置应该还很多,等我有空更新哈,先这样



太阳http代理AD
回复

使用道具 举报