【起手式】开始一个Asp .net core WebApi项目-有木酱的小屋

在这篇文章，我们来试着搭建一个完备可用的Asp .net core WebApi项目，以便我们后续的业务开发。

创建工程

首先第一步自然就是创建一个新的工程了，直接创建一个最简单的啥都没有的的api工程即可

dotnet new webapi -o ProjectName

Service Extensions

C#有个非常有趣的扩展方法功能，利用它，我们可以把代码搞得更加整洁一点。

新建一个静态类，我们把它叫做ServiceExtensions

然后，所有配置依赖注入服务相关的东西，我们都使用扩展方法的形式写在这里，这样一来，Startup类里面就会简洁许多。

OpenID Connect

通常，我们的项目使用OIDC （OpenID Connect）Jwt Bearer 来保护Api资源，所以我们先来配置oidc相关内容。

首先我们需要引入一个Nuget包

这里我们直接使用IdentityServer4提供的包，当然也可以使用别的，比如Microsoft.AspNetCore.Authentication.JwtBearer等等

然后我们在ServiceExtensions中编写代码如下：

using IdentityServer4.AccessTokenValidation;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace Meow.Api
{
    public static class ServiceExtensions
    {
        public static void AddAuthenticationWithOIDC(this IServiceCollection services , IConfiguration configuration)
        {
            services.AddAuthentication(IdentityServerAuthenticationDefaults.AuthenticationScheme)
                .AddIdentityServerAuthentication(options =>
                {
                    options.Authority = configuration["Oidc:Authority"];
                    options.ApiName = configuration["Oidc:ApiName"];
                    options.RequireHttpsMetadata = configuration.GetValue<bool>("Oidc:RequireHttps");
                });
        }
    }
}

其中”Oidc:Authority”等相关配置项需要写道”appsettings.json”中。

然后，我们通过上面的扩展方法，向Startup的ConfigureServices配置Oidc相关内容：

同样的，我们得配置一下管道

Swagger

对于WebApi项目来说，Swagger是个非常有用的大宝贝。尤其在调试Api时候，网页上直接点点就完事了，省的去开postman了，非常方便。

首先，依然是先添加个Nuget包进来：

然后继续编写扩展方法：

public static void AddSwagger(this IServiceCollection services, IConfiguration configuration)
        {
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
                {
                    Title = configuration["Swagger:v1:Title"],
                    Version = configuration["Swagger:v1:VersionName"],
                    Description = configuration["Swagger:v1:Desc"],
                });

                // Set the comments path for the Swagger JSON and UI.
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                options.IncludeXmlComments(xmlPath);


                //Auth
                var dict_scopes = new Dictionary<string, string>();
                string[] scopes_arr = configuration.GetSection("Swagger:Oidc:Scopes").Get<string[]>();
                string[] scopes_desc_arr = configuration.GetSection("Swagger:Oidc:ScopesDesc").Get<string[]>();
                for(var i = 0; i < scopes_arr.Length; i++)
                {
                    dict_scopes.Add(scopes_arr[i], (scopes_desc_arr.Length > i) ? scopes_desc_arr[i] : scopes_arr[i]);
                }
                options.AddSecurityDefinition("oidc", new OpenApiSecurityScheme 
                {
                    Type = SecuritySchemeType.OAuth2,
                    Flows = new OpenApiOAuthFlows
                    {
                        Implicit = new OpenApiOAuthFlow
                        {
                            AuthorizationUrl = new Uri($"{configuration["Oidc:Authority"]}/connect/authorize"),
                            Scopes = dict_scopes
                        }
                    }
                });

                options.OperationFilter<AuthResponsesOperationFilter>();
            });
        }

这里就有点复杂了，一样样来，

首先，这样直接运行会报错，因为默认情况下这个工程不会生成xml文档，而我们Swagger是需要xml文档来读取注释信息的，于是就报错了，我们得改改。

打开这个项目的.csproj文件，添加如下：

<PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Swagger部分对应的appsetting.json配置如下：

然后，最后options.OperationFilter<AuthResponsesOperationFilter>(); 这一句中的AuthResponsesOperationFilter，代码如下：

using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNetCore.Authorization;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace Meow.Api
{
    public class AuthResponsesOperationFilter : IOperationFilter
    {
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            var hasAuthorize = context.MethodInfo.DeclaringType.GetCustomAttributes(true)
                .Union(context.MethodInfo.GetCustomAttributes(true))
                .OfType<AuthorizeAttribute>()
                .Any();

            if (hasAuthorize)
            {
                operation.Responses.Add("401", new OpenApiResponse { Description = "暂无权限访问" });
                operation.Responses.Add("403", new OpenApiResponse { Description = "禁止访问" });

                operation.Security = new List<OpenApiSecurityRequirement>();
                operation.Security.Add(new OpenApiSecurityRequirement
                {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oidc" }
                        },
                        new[] { "Api1" , "openid" } //这里改成你自己的Scopes
                    }
                });
            }
        }
    }
}

最后给它添加到Startup类里