asp.net core使用Swashbuckle.AspNetCore(swagger)生成接口文档

asp.net core中使用Swashbuckle.AspNetCore生成接口文档

Swashbuckle.AspNetCore:swagger的asp.net core实现 项目地址:https://github.com/domaindrivendev/Swashbuckle.AspNetCore 仔细看了下readme,发现在百度找半天的东西其实readme里面就有...

开局一张图,然后开始编,一些基本的asp.net core东西就不再赘述,本文只对Swashbuckle.AspNetCore的几个使用要点进行描述。

如上图所示,包含功能如下(完整示例见文末)

  1. 基础使用,添加controler的说明(IDocumentFilter)
  2. 汉化操作按钮
  3. 添加通用参数(header)-实现IOperationFilter
  4. 多版本控制(暂时见demo)
  5. 使用JWT的简单接口验证(暂时见demo)

构建一个webapi项目并使用swagger

  1. 新建asp.net core webapi项目 dotnet new webapi
  2. 安装nuget包:Swashbuckle.AspNetCore,本文使用版本1.1.0,.net core版本2.0+
  3. 编辑解决方案添加(或者在vs中项目属性->生成->勾选生成xml文档文件)如下配置片段
      <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
        <DocumentationFile>bin\Debug\netcoreapp2.0\项目名称.xml</DocumentationFile>
      </PropertyGroup>
  1. 使用Swagger并注入汉化脚本

c.SwaggerDoc配置接口描述信息 c.OperationFilter可通过IOperationFilter接口去添加一些公共的参数 c.DocumentFilter通过IDocumentFilter接口去生成控制器的标签(描述) 注:ConfigureServices的方法返回值修改了,为了能够正常的使用ServiceLocator获取服务

private const string _Project_Name = "AspNetCoreSwaggerDemo";//nameof(AspNetCoreSwaggerDemo);
public IServiceProvider ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
    services.AddSingleton(new ApiTokenConfig("A3FFB16D-D2C0-4F25-BACE-1B9E5AB614A6"));
    services.AddScoped<IApiTokenService, ApiTokenService>();
    services.AddSwaggerGen(c =>
    {
        typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
        {
            c.SwaggerDoc(version, new Swashbuckle.AspNetCore.Swagger.Info
             {
                 Version = version,
                 Title = $"{_Project_Name} 接口文档",
                 Description = $"{_Project_Name} HTTP API " + version,
                 TermsOfService = "None"
             });
        });
        var basePath = Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationBasePath;
        var xmlPath = System.IO.Path.Combine(basePath, $"{_Project_Name}.xml");
        c.IncludeXmlComments(xmlPath);
        //添加自定义参数,可通过一些特性标记去判断是否添加
        c.OperationFilter<AssignOperationVendorExtensions>();
        //添加对控制器的标签(描述)
        c.DocumentFilter<ApplyTagDescriptions>();
    });

    services.AddMvc();
    return services.BuildServiceProvider();
}

使用InjectOnCompleteJavaScript注入汉化js脚本即可 注:我在这个汉化脚本中添加了保存和读取赋值token/版本的js代码 ApiVersions为枚举,配置api版本,以期通过CustomRoute特性标记解决历史api问题。

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        //ApiVersions为自定义的版本枚举
        typeof(ApiVersions)
        .GetEnumNames()
        .OrderByDescending(e => e)
        .ToList()
        .ForEach(version =>
        {
            //版本控制
            c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{_Project_Name} {version}");
         });
         //注入汉化脚本
         c.InjectOnCompleteJavaScript($"/swagger_translator.js");
    });
    //通过ServiceLocator.Resolve<Service接口>()获取注入的服务
    ServiceLocator.Configure(app.ApplicationServices);
    app.UseStaticFiles();
    app.UseMvc();
}

实现 IDocumentFilterIOperationFilter

通过IOperationFilter接口可以添加一些公共的参数,添加参数到header或者上传图片等 通过IDocumentFilter接口可以生成控制器的标签(描述) 调用方式分别为: c.OperationFilter<AssignOperationVendorExtensions>(); c.DocumentFilter<ApplyTagDescriptions>();

//添加标签
public class ApplyTagDescriptions : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Tags = new List<Tag>
        {
            //添加对应的控制器描述 这个是好不容易在issues里面翻到的
            new Tag { Name = "Account", Description = "登录相关接口" },
            new Tag { Name = "UserCenter", Description = "用户中心接}
        };
    }
}
//添加通用参数,若in='header'则添加到header中,默认query参数
public class AssignOperationVendorExtensions : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        operation.Parameters = operation.Parameters ?? new List<IParameter>();
        //MemberAuthorizeAttribute 自定义的身份验证特性标记
        var isAuthor = operation != null && context != null && context.ApiDescription.ControllerAttributes().Any(e => e.GetType() == typeof(MemberAuthorizeAttribute)) || context.ApiDescription.ActionAttributes().Any(e => e.GetType() == typeof(MemberAuthorizeAttribute));
        if (isAuthor)
        {
            //in query header 
            operation.Parameters.Add(new NonBodyParameter() { 
                    Name = "x-token", 
                    In = "header", //query formData ..
                    Description = "身份验证票据", 
                    Required = false, 
                    Type = "string" 
           });
        }
    }
}

配置完成后,给Controler,Action添加上注释和请求类型就可以访问/swagger查看你的api文档了~ 注:

  1. action方法或者控制器(或者继承的)必须有一个包含[Route]特性标记
  2. action方法必须添加请求类型[HttpGet]/[HttpPost]/..

如何自动将token保存并赋值

使用js生成了文本框到.authorize-wrapper,将值保存到了本地存储中,然后会根据接口版本将版本号参数进行复制

$(function () {
    //汉化
    window.SwaggerTranslator.translate();
    /***************下面是添加的token相关代码*******************/
    window.saveToken=function() {
        var test_token = $("#customtoken").val();
        localStorage.setItem("test_x_token", $("#customtoken").val());
        $("input[name='X-Token']").val(test_token)
    }
    //token保存
    var test_token = localStorage.getItem("test_x_token")||"";
    $(".authorize-wrapper").append("X-Token:<input type='text' id='customtoken' value='" + test_token +"' style='width:50%' /> <button onClick='saveToken()'>保存</button>")
    $("input[name='X-Token']").val(test_token)
    $("input[name='X-Version']").val(swaggerUi.api.info.version)

});

如何忽略一个接口

为Controller或者Action方法上添加特性标记[ApiExplorerSettings(IgnoreApi =true)]即可

除了swagger发现还有好多东西要写,但是一篇貌似又太多了,so..请听下周分解吧 这篇文章是先有demo,有需要的可以至文末下载demo查看,大概还有如下几个可以写的地方

  • JWT的使用
  • 自定义路由特性标记的扩展
  • api版本的控制

文章完整示例

Demo下载 Demo仓库地址

注:Demo 未修改默认启动路径,故应使用 /swagger/ 访问文档:,也可自行修改 /Properties/launchSettings.json 配置默认路径

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏木宛城主

基于Socket的网络聊天室编程(第一版)

一:什么是套接字 在网络编程中最常用的方案便是Client/Server (客户机/服务器)模型。在这种方案中客户应用程序向服务器程序请求服务。一个服务程序通常...

2785
来自专栏Puppeteer学习

一步一步学Vue(九)

1604
来自专栏james大数据架构

资源等待类型sys.dm_os_wait_stats

动态管理视图  sys.dm_os_wait_stats  返回执行的线程所遇到的所有等待的相关信息。可以使用该聚合视图来诊断 SQL Server 以及特定查...

2237
来自专栏逸鹏说道

使用OAuth打造webapi认证服务供自己的客户端使用

一、什么是OAuth OAuth是一个关于授权(Authorization)的开放网络标准,目前的版本是2.0版。注意是Authorization(授权),而不...

3836
来自专栏攻城狮的动态

iOS面试题梳理(三)

3747
来自专栏Java帮帮-微信公众号-技术文章全总结

JavaWeb11-jsp.cookie.session(1)

? Jsp&cookie & session 一.jsp 1. jsp的介绍 JSP全名为Java Server Pages,中文名叫java服务器页面,本质...

2995
来自专栏魏琼东

分布式消息总线,基于.NET Socket Tcp的发布-订阅框架之离线支持,附代码下载

     在前面的分享一个分布式消息总线,基于.NET Socket Tcp的发布-订阅框架,附代码下载一文之中给大家分享和介绍了一个极其简单也非常容易上的基于...

1130
来自专栏逸鹏说道

Linux 部署ASP.NET SQLite 应用 的坎坷之旅 附demo及源码

Linux 部署ASP.NET SQLite 应用 的坎坷之旅。文章底部 附示例代码。 有一台闲置的Linux VPS,尝试着部署一下.NET 程序,结果就踏上...

3743
来自专栏一个爱瞎折腾的程序猿

在asp.net core2.1中添加中间件以扩展Swashbuckle.AspNetCore3.0支持简单的文档访问权限控制

在此之前的接口项目中,若使用了 Swashbuckle.AspNetCore,都是控制其只在开发环境使用,不会就这样将其发布到生产环境(安全第一) 。 那么,...

1681
来自专栏Bug生活2048

.net core项目实战之基于Restful API+Swagger项目搭建

然后右击你的项目,在属性中,勾选下生成XML文档文件,Swagger会自动解析对应的XML进行匹配。

1341

扫码关注云+社区

领取腾讯云代金券