zoukankan      html  css  js  c++  java
  • swagger ui

    Swagger这个优秀的开源项目相信大家都用过,不多介绍了,这里简单记录一下使用过程。

    开源地址:https://github.com/domaindrivendev/Swashbuckle.AspNetCore

    在项目中添加组件

    Install-Package Swashbuckle.AspNetCore

    下面用最少的代码完成接入,在Startup启动项中配置。

    public void ConfigureServices(IServiceCollection services) { ... services.AddSwaggerGen(x => { x.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Version = "v1.0.0", Title = "Api", Description = "XXX Api" }); }); ... }
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { ... app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "API"); }); ... }

    这样便完成了,swagger会自动发现我们在controller中写的api,默认打开页面为:~/swagger

    同时还可以让其支持分组展示,只需要像上面一样配置多个节点信息接口,如下面代码:

    services.AddSwaggerGen(options => { options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Version = "v1.0.0", Title = "Api1", Description = "XXX Api1" }); options.SwaggerDoc("v2", new Microsoft.OpenApi.Models.OpenApiInfo { Version = "v1.0.0", Title = "Api2", Description = "XXX Api2" }); });
    app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "API1"); c.SwaggerEndpoint("/swagger/v2/swagger.json", "API2"); });

    如果在控制器中不指定接口的分组名称,那么每个分组都会显示这个接口,如果需要单独指定可以使用特性[ApiExplorerSettings(GroupName = "v1")]这样。

    如果想要显示接口的注释,模型的注释等信息,需要我们将对应的项目设置输出XML文件,并在代码中使用options.IncludeXmlComments(xxx.xml)即可。

    下面来说一下swagger的一些其它功能,当我们接口开启了JWT方式的认证,默认swagger是不支持的,需要我们手动去适配一下。

    需要额外添加一个组件

    Install-Package Swashbuckle.AspNetCore.Filters
    context.Services.AddSwaggerGen(options => { ... var security = new OpenApiSecurityScheme { Description = "<b>please enter <code>Bearer {Token}</code> for authentication.</b>", Name = "Authorization", In = ParameterLocation.Header, Type = SecuritySchemeType.ApiKey }; options.AddSecurityDefinition("oauth2", security); options.AddSecurityRequirement(new OpenApiSecurityRequirement { { security, null } }); options.OperationFilter<AddResponseHeadersFilter>(); options.OperationFilter<AppendAuthorizeToSummaryOperationFilter>(); options.OperationFilter<SecurityRequirementsOperationFilter>(); });

    现在UI界面便会出现小绿锁,这样就可以很方便的在swagger上进行需要授权的接口调试工作了。

    同时swagger还支持一些高级操作,比如自定义UI界面、注入JS、CSS代码,因为这个用的不是很多,实际要用的时候可以去GitHub查看使用方法。

    // Customize index.html app.UseSwaggerUI(c => { c.IndexStream = () => GetType().Assembly.GetManifestResourceStream("CustomUIIndex.Swagger.index.html"); }); // Inject Custom CSS app.UseSwaggerUI(c => { ... c.InjectStylesheet("/swagger-ui/custom.css"); }

    这里还要说一下swagger的过滤器,我们可以实现IDocumentFilter接口,来实现自定义的接口排序,个性化接口描述,以及各种骚操作,比如我们想要隐藏某些API,当然隐藏API可以使用.NET Core 的特性[ApiExplorerSettings(IgnoreApi = true)]实现。

    这里隐藏是指不在swaggerUI中显示,实际接口还是存在的。

    public class SwaggerDocumentFilter : IDocumentFilter { public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context) { var tags = new List<OpenApiTag> { new OpenApiTag { Name = "Authentication", Description = "Authentication", ExternalDocs = new OpenApiExternalDocs { Description = "Authentication" } }, new OpenApiTag { Name = "Localization", Description = "Localization", ExternalDocs = new OpenApiExternalDocs { Description = "Localization" } } }; swaggerDoc.Tags = tags.OrderBy(x => x.Name).ToList(); var apis = context.ApiDescriptions.Where(x => x.RelativePath.Contains("abp")); if (apis.Any()) { foreach (var item in apis) { swaggerDoc.Paths.Remove("/" + item.RelativePath); } } } }

    上面这段代码,使用了abp框架搭建的项目,abp默认实现了一部分接口,如果我们不需要的话就可以使用上面的方式进行过滤。

    最后一点,如果我们用了第三方框架,像上面说的abp,或者使用了动态API生成的组件,比如:Plus.AutoApi,想要在swagger中显示出api接口,需要添加下面这句代码。

    context.Services.AddSwaggerGen(options => { ... options.DocInclusionPredicate((docName, description) => true); ... });

    swagger推出的同时还推出了一款工具ReDoc,下面也简单介绍一下。

    ReDocswagger比较类似,只是一个文档展示工具,不提供接口调试的功能。

    他们的使用方式基本一致,先在项目中添加一下组件

    Install-Package Swashbuckle.AspNetCore.ReDoc

    OnApplicationInitialization中直接添加一句配置即可。

    app.UseReDoc();

    它支持多种参数选项,可以自行查看,默认打开页面为:~/api-docs,下面是他的UI界面。

    __EOF__

    本文作者:阿星Plus
    本文链接:https://www.cnblogs.com/meowv/p/13614273.html
    关于博主:评论和私信会在第一时间回复。或者直接私信我。
    版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
    声援博主:如果您觉得文章对您有帮助,可以点击文章右下角推荐】一下。您的鼓励是博主的最大动力!
     
     

    NetCore生产环境禁用Swagger教程

    1. NetCore有两个配置文件分辨是appsetting.json和appsetting.[Environment].json,通过区分这两个文件来识别生产环境和开发环境。
    2. 首先在appsetting.json添加
    "UseSwagger":"false"
    
    1. 在appsetting.Development.json添加
    "UseSwagger":"true"
    
    1. 在Startup.cs中的services.AddSwaggerGen()和app.UseSwagger();app.UseSwaggerUI();根据配置加上判断。
                if (Configuration.GetSection("UseSwagger").Value == "true")
                {
                    services.AddSwaggerGen();
                }
                if (Configuration.GetSection("UseSwagger").Value == "true")
                {
                    app.UseSwagger();
                    app.UseSwaggerUI();
                }
    
    1. 最后只需要根据所需环境修改dockerfile即可
    ENV ASPNETCORE_ENVIRONMENT=Development
    

    NetCore生产环境禁用Swagger教程

    标签:pre   配置   section   add   env   json   

    原文:https://www.cnblogs.com/Jackyye/p/13070587.html

  • 相关阅读:
    codeforces 980A Links and Pearls
    zoj 3640 Help Me Escape
    sgu 495 Kids and Prizes
    poj 3071 Football
    hdu 3853 LOOPS
    hdu 4035 Maze
    hdu 4405 Aeroplane chess
    poj 2096 Collecting Bugs
    scu 4444 Travel
    zoj 3870 Team Formation
  • 原文地址:https://www.cnblogs.com/zengpeng/p/13625050.html
Copyright © 2011-2022 走看看