.net core swagger api 文档

简易版Swagger文档

startup.cs 中添加如下代码

ConfigureServices方法：

           services.AddSwaggerGen(c =>
            {
                //swagger版本信息
                c.SwaggerDoc("v1", new OpenApiInfo 
                {
                    Version = "v1",
                    Title = "WebApi", 
                    Description="测试webpai",

                });

                //使用xml
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath, true);//true 表示启用controller注释
            });

Configure方法：

            app.UseSwagger();
            app.UseSwaggerUI(c => 
            {
                //如果使用目录及iis或反向代理，需要使用./设置为相对路径：./swagger/v1/swagger.json
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApi v1");

                //在根目录查看swagger文档
                c.RoutePrefix = string.Empty;
                
                //默认格式 不展开，full=全部展开，list=只展开列表，none=都不展开
                c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None);
            });

在项目 csproj文件中添加代码

	  <!--启用xml注释-->
	  <GenerateDocumentationFile>true</GenerateDocumentationFile>
	  <!--取消1591警告-->
	  <NoWarn>$(Nowarn);1591</NoWarn>

到这步，swagger文档就配置完成了

---

添加jwt授权

在 startup ConfigureServices 中添加如下代码

           services.AddSwaggerGen(c =>
            {
                //swagger版本信息
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = "WebApi",
                    Description = "测试webpai",

                });

                //使用xml
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath, true);//true 表示启用控制器的注释

                //添加一个或多个“securitydefinition”，描述如何保护你的API，
                //到生成的Swagger
                c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
                {
                    Description = "JWT授权(数据将在请求头中进行传输) 直接在下框中输入Bearer {token}（注意两者之间是一个空格",
                    Name = "Authorization",//jwt默认参数名称
                    In = ParameterLocation.Header,//放在请求头中
                    Type = SecuritySchemeType.ApiKey
                });

                //添加全局安全性需求
                c.AddSecurityRequirement(new OpenApiSecurityRequirement
                {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference=new OpenApiReference()
                            {
                                Id="Bearer",
                                Type=ReferenceType.SecurityScheme
                            }
                        }
                        , Array.Empty<string>()
                    }
                });

swagger 小技巧

1. 弃用API:在方法或控制器添加特性：[Obsolete]
2. 隐藏API:在方法或控制器添加特性：[ApiExplorerSettings(IgnoreApi =true)]
3. 上传文件：参数类型为IFormFile
4. 接口备注：可在注释 <remarks>中添加接口描述