.net core 3.1 + Swagger 5.0 初步配置
手捧微尘 人气:0附言:账号创建到现在也6年多了,都没有写过任何文章,第一次试水,见谅。这文章是之前.net framework 转到.net core,搭建swagger的时候,写在云笔记里面。
废话不说,进入正文。
- vs2019创建webapi项目,Nuget引入Swashbuckle.AspNetCore
- Startup.cs添加相关配置
- ConfigureServices 方法中添加配置,注意大小写,linux系统区分大小写
-
//注册Swagger生成器,定义一个和多个Swagger 文档 services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); // 为 Swagger JSON and UI设置xml文档注释路径 //获取应用程序所在目录(绝对,不受工作目录影响,建议采用此方法获取路径) var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location); var xmlPath = Path.Combine(basePath, "SwaggerCoreTest.xml"); var xmlPath2 = Path.Combine(basePath, "SwaggerCode.xml"); c.IncludeXmlComments(xmlPath, true);//true为控制器注释也读取出来 c.IncludeXmlComments(xmlPath2); c.CustomSchemaIds((type) => type.FullName);// 解决相同类名会报错的问题 });
- Configure方法中添加配置代码
-
//启用中间件服务生成Swagger作为JSON终结点 app.UseSwagger(); //启用中间件服务对swagger-ui,指定Swagger JSON终结点 app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); c.RoutePrefix = string.Empty;//设置首页为Swagger //c.DocExpansion(DocExpansion.None);//设置为none可折叠所有方法 c.DefaultModelsExpandDepth(-1);//设置为-1 可不显示models });
- 设置生成XML文件,项目-属性-生成,勾选xml文档文件
- 配置Authorization,在AddSwaggerGen中添加
//添加一个必须的全局安全信息,和AddSecurityDefinition方法指定的方案名称要一致,这里是Bearer。 c.AddSecurityRequirement(new OpenApiSecurityRequirement { { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = JwtBearerDefaults.AuthenticationScheme } }, new string[] { } } }); c.AddSecurityDefinition(JwtBearerDefaults.AuthenticationScheme, new OpenApiSecurityScheme { Description = "JWT授权(数据将在请求头中进行传输) 参数结构: \"Authorization: Bearer {token}\"", Name = "Authorization",//jwt默认的参数名称 In = ParameterLocation.Header,//jwt默认存放Authorization信息的位置(请求头中) Type = SecuritySchemeType.ApiKey });
- 配置接口不对外展示 ,在控制器/行为中添加标签特性:[ApiExplorerSettings(IgnoreApi = true)],如
/// <summary> /// 测试接口 /// </summary> [AllowAnonymous] [ApiController] public class TestController : ControllerBase { /// <summary> /// Get /// </summary> /// <returns></returns> [HttpGet] [Route("api/[controller]")] [ApiExplorerSettings(IgnoreApi = true)] public string Get() { return DateTime.Now.ToString(); } }
采坑:发布项目后,在服务器项目中未找到对应的xml文件,处理方式:修改有生成xml文件的的项目的csproj,添加配置,比如API项目和Model项目都会生成xml文件,则两个项目的csproj文件都加上以下配置。
<PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup>
加载全部内容