当前位置:首页 > 服务端 > asp.net core 3.0 中使用 swagger

asp.net core 3.0 中使用 swagger

2022年08月05日 19:03:19服务端10

asp.net core 3.0 中使用 swagger

Intro

上次更新了 asp.net core 3.0 简单的记录了一下 swagger 的使用 ,详细可以参考asp.net core3.0更新简记,那个项目的 api 比较简单,都是匿名接口不涉及到认证以及 api 版本控制,最近把另外一个 api 项目升级到了 3.0,还是遇到了一些问题,这里单独写一篇文章介绍,避免踩坑。

Swagger 基本使用

安装 nuget 包 Swashbuckle.AspNetCore,需要使用 5.0.x 版本,使用最新的 5.0.0-rc 版本(还没发稳定版,需要显示预览版本才能看到)

swagger 服务注册:

services.AddSwaggerGen(option =>
    {
        option.SwaggerDoc("sparktodo", new OpenApiInfo
        {
            Version = "v1",
            Title = "SparkTodo API",
            Description = "API for SparkTodo",
            Contact = new OpenApiContact() { Name = "WeihanLi", Email = "weihanli@outlook.com" }
        });
        
        // include document file
        option.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{typeof(Startup).Assembly.GetName().Name}.xml"), true);
    });

中间件配置:

//Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();
//Enable middleware to serve swagger-ui (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint
app.UseSwaggerUI(option =>
{
    option.SwaggerEndpoint("/swagger/sparktodo/swagger.json", "sparktodo Docs");

    option.RoutePrefix = string.Empty;
    option.DocumentTitle = "SparkTodo API";
});

为 Swagger 添加 Bearer Token 认证

services.AddSwaggerGen(option =>
{
    // ...

    // Add security definitions
    option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
    {
        Description = "Please enter into field the word 'Bearer' followed by a space and the JWT value",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
    });
    option.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        { new OpenApiSecurityScheme
        {
            Reference = new OpenApiReference()
            {
                Id = "Bearer",
                Type = ReferenceType.SecurityScheme
            }
        }, Array.Empty<string>() }
    });
});

支持多个 ApiVersion

services.AddApiVersioning(options =>
    {
        options.AssumeDefaultVersionWhenUnspecified = true;
        options.DefaultApiVersion = ApiVersion.Default;
        options.ReportApiVersions = true;
    });

services.AddSwaggerGen(option =>
{
    // ...

    option.SwaggerDoc("v1", new OpenApiInfo { Version = "v1", Title = "API V1" });
    option.SwaggerDoc("v2", new OpenApiInfo { Version = "v2", Title = "API V2" });

    option.DocInclusionPredicate((docName, apiDesc) =>
    {
        var versions = apiDesc.CustomAttributes()
            .OfType<ApiVersionAttribute>()
            .SelectMany(attr => attr.Versions);

        return versions.Any(v => $"v{v.ToString()}" == docName);
    });

    option.OperationFilter<RemoveVersionParameterOperationFilter>();
    option.DocumentFilter<SetVersionInPathDocumentFilter>();
});

自定义 Api version 相关的 OperationFilter:

public class SetVersionInPathDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        var updatedPaths = new OpenApiPaths();

        foreach (var entry in swaggerDoc.Paths)
        {
            updatedPaths.Add(
                entry.Key.Replace("v{version}", swaggerDoc.Info.Version),
                entry.Value);
        }

        swaggerDoc.Paths = updatedPaths;
    }
}

public class RemoveVersionParameterOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // Remove version parameter from all Operations
        var versionParameter = operation.Parameters.Single(p => p.Name == "version");
        operation.Parameters.Remove(versionParameter);
    }
}

中间件配置:

//Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();
//Enable middleware to serve swagger-ui (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint
app.UseSwaggerUI(option =>
{
    option.SwaggerEndpoint("/swagger/v2/swagger.json", "V2 Docs");
    option.SwaggerEndpoint("/swagger/v1/swagger.json", "V1 Docs");

    option.RoutePrefix = string.Empty;
    option.DocumentTitle = "SparkTodo API";
});

最终 swagger 效果

asp.net core 3.0 中使用 swagger _ JavaClub全栈架构师技术笔记

asp.net core 3.0 中使用 swagger _ JavaClub全栈架构师技术笔记

Memo

上面的配置来自 https://github.com/WeihanLi/SparkTodo 这个项目,要获取代码可以参考这个项目

Reference

作者:WeihanLi
来源链接:https://www.cnblogs.com/weihanli/p/ues-swagger-in-aspnetcore3_0.html

版权声明:
1、JavaClub(https://www.javaclub.cn)以学习交流为目的,由作者投稿、网友推荐和小编整理收藏优秀的IT技术及相关内容,包括但不限于文字、图片、音频、视频、软件、程序等,其均来自互联网,本站不享有版权,版权归原作者所有。

2、本站提供的内容仅用于个人学习、研究或欣赏,以及其他非商业性或非盈利性用途,但同时应遵守著作权法及其他相关法律的规定,不得侵犯相关权利人及本网站的合法权利。
3、本网站内容原作者如不愿意在本网站刊登内容,请及时通知本站(javaclubcn@163.com),我们将第一时间核实后及时予以删除。


本文链接:https://www.javaclub.cn/server/17771.html

标签: Swagger
分享给朋友:

“asp.net core 3.0 中使用 swagger” 的相关文章

Maven + SpringMVC项目集成Swagger

Maven + SpringMVC项目集成Swagger

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。 作用:  接...

.net core swagger汉化

.net core swagger汉化

基本swagger使用不再详解,具体百度其它帖子 1.将汉化的swagger js文件复制到项目根目录中 js代码如下 1 'use strict'; 2 3 /** 4 * Translator for documentatio...

springboot成神之——swagger文档自动生成工具

springboot成神之——swagger文档自动生成工具

本文讲解如何在spring-boot中使用swagger文档自动生成工具 目录结构 说明 依赖 SwaggerConfig 开启api界面 JSR 303注释信息 Swagger核...

Swagger实现API文档功能

Swagger实现API文档功能

介绍: wagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案。简单的说就是一款让你更好的书写API文档的框架。 我们为什么选择swagger,现在的网站开发结果越来越注重前后端的分离,比如以前的...

.net core在Ocelot网关中统一配置Swagger

.net core在Ocelot网关中统一配置Swagger

最近在做微服务的时候,由于我们是采用前后端分离来开发的,提供给前端的直接是Swagger,如果Swagger分布在各个API中,前端查看Swagger的时候非常不便,因此,我们试着将Swagger集中放到网关中。 这里我用两个API项目(一个BasicDataApi,一个User...

使用Swagger直接上传文件的方法

使用Swagger直接上传文件的方法

经常使用swagger,可以通过设置[ProducesResponseType]标记接口的返回信息;swagger也能通过接口的参数列表,自动获得发送的数据结构信息。 不过有一个例外,就是上传文件的时候,设置了[Consumes]的内容为multi-part/form-data,...

swagger整合springboot的使用

swagger整合springboot的使用

什么是swagger? Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服...

配置 Swagger 带 token 访问的两种方式

配置 Swagger 带 token 访问的两种方式

推荐使用全局的方式 1. 每个接口单独传 import com.google.common.collect.Lists; import org.springframework.beans.factory.annotation.Value; impo...

ABP使用NSwagStudio for Swagger Api生成ServiceProxies

ABP使用NSwagStudio for Swagger Api生成ServiceProxies

案例主要是使用NSwag来生成ABP for angular 2+的客户端代码。 NSwagStudio 下载地址 比较强大、可以生成TypeScript、WebApi Controller、CSharp Client  1:运行Web.Host项目&n...

asp.net core 集成swagger ui

asp.net core 集成swagger ui

什么是Swagger? 说swagger 之前,我们先说一下OpenApi 规范。 OpenApi 是一种和语言无关的用于描述RESTAPIs 接口功能的一种规范,对RESTAPIs 接口的描述包括: 接口参数信息、接口返回值信息、api 功能描述、请求路径等。 这里...

发表评论

访客

◎欢迎参与讨论,请在这里发表您的看法和观点。