欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

asp.net core web api 生成 swagger 文档

程序员文章站 2022-05-18 15:41:45
在前后端分离的开发模式下,文档就显得比较重要,哪个接口要传哪些参数,如果一两个接口还好,口头上直接沟通好就可以了,如果接口多了就有点不适用了,没有接口文档会大大提高前后端的沟通成本。而 asp.net core 可以通过 [Swashbuckle.AspNetCore](https://github... ......

asp.net core web api 生成 swagger 文档

intro

在前后端分离的开发模式下,文档就显得比较重要,哪个接口要传哪些参数,如果一两个接口还好,口头上直接沟通好就可以了,如果接口多了就有点不适用了,没有接口文档会大大提高前后端的沟通成本。而 asp.net core 可以通过 swashbuckle.aspnetcore 很方便的集成 swagger 文档,相比之前 nodejs(express) 和 swagger 集成就很麻烦了,大概这就是强类型语言的优势吧。c# 是最好的编程语言~~~

集成 swagger

  1. 配置 model 以及 api 项目生成 xml 文档

    在对应项目的项目文件中加入下面的代码,配置生成 xml 文档

      <propertygroup>    
        <generatedocumentationfile>true</generatedocumentationfile>
        <nowarn>$(nowarn);1591</nowarn>
      </propertygroup>
  2. 在 web 项目上引用 swashbuckle.aspnetcore

  3. 配置 web 项目使用 swagger

    1. 配置 configureservices,配置示例代码

      services.addswaggergen(options =>
      {
          options.swaggerdoc(applicationhelper.applicationname, new info { title = "活动室预约系统 api", version = "1.0" });
      
          options.includexmlcomments(path.combine(appcontext.basedirectory, $"{typeof(notice).assembly.getname().name}.xml")); //使用model项目的xml文档
          options.includexmlcomments(path.combine(appcontext.basedirectory, $"{typeof(noticecontroller).assembly.getname().name}.xml"), true); //使用apicontroller项目的xml文档
      });
    2. 配置 configure ,配置示例代码

      app
      .useswagger()
      .useswaggerui(c =>
      {
          // c.routeprefix = string.empty; //配置swagger ui前缀,默认值是 "swagger",你可以使用 "string.empty"来配置首页就是 swagger ui
          c.swaggerendpoint($"/swagger/{applicationhelper.applicationname}/swagger.json", "活动室预约系统 api");
          c.documenttitle = "活动室预约系统 api";
      });
    3. 现在重新启动项目,访问 "/swagger" 就可以看到效果了

其他小技巧

  1. 忽略某些api,可以在controller 上加attribute[apiexplorersettings(ignoreapi = true)],这个attribute 支持继承,也就是说你可以在一个basecontroller 上加这个 attribute ,这样继承于这个 basecontroller 的 controller 的接口都不会显示在 swagger 文档中

  2. 添加自定义请求头参数,可以自定义一个 operationfilter

    1. 定义 operationfilter 示例

      public class authorizationoperationfilter : ioperationfilter
      {
          public void apply(operation operation, operationfiltercontext context)
          {
              if (operation.parameters == null)
              {
                  operation.parameters = new list<iparameter>();
              }
              var filterpipeline = context.apidescription.actiondescriptor.filterdescriptors;
              var isauthorized = filterpipeline.any(filter => filter.filter is authorizefilter);
              var allowanonymous = filterpipeline.any(filter => filter.filter is iallowanonymousfilter);
      
              if (isauthorized && !allowanonymous)
              {
                  operation.parameters.add(new nonbodyparameter()
                  {
                      name = "authorization",
                      in = "header",
                      type = "string",
                      description = "access token",
                      required = true
                  });
              }
          }
      }
      
      public class apiversionoperationfilter : ioperationfilter
      {
          public void apply(operation operation, operationfiltercontext context)
          {
              if (operation.parameters == null)
              {
                  operation.parameters = new list<iparameter>();
              }
              context.apidescription.trygetmethodinfo(out var methodinfo);
      
              if (methodinfo.declaringtype.isdefined(typeof(apiversionattribute), true))
              {
                  operation.parameters.add(new nonbodyparameter()
                  {
                      name = "api-version",
                      in = "header",
                      type = "string",
                      description = "api-version",
                      required = true,
                      default = "1.0"
                  });
              }
          }
      }
    2. 配置 swagger 使用 operationfilter

      services.addswaggergen(options =>
      {
          // ...
          options.operationfilter<authorizationoperationfilter>();
      });
  3. 更多技术及骚操作参考官方文档介绍 https://github.com/domaindrivendev/swashbuckle.aspnetcore

示例

api 接口 swagger 文档

asp.net core web api 生成 swagger 文档

这个api 接口文档只显示了api接口,服务器端其他的controller 使用了上面提到的 [apiexplorersettings(ignoreapi = true)] 忽略了

最近我的活动室预约的项目增加了一个前后端分离的 angular + marterial 的客户端,体验地址

reference