提供QuickApi对NSwag的兼容支持

[vipwan]

兼容NSwag的成本较高,需要做的工作比较多,欢迎有兴趣的伙伴贡献代码 😃

[vipwan]

RicoSuter/NSwag#4163

[vipwan]

    [QuickApi("content", Group = "hello", Verbs = Verb.GET)]
    [QuickApiSummary("ContentApi", "ContentApi")]
    public class ContentApi : BaseQuickApi<EmptyRequest, ContentResponse>
    {
        public override Task<ContentResponse> ExecuteAsync(EmptyRequest request)
        {
            return Task.FromResult(new ContentResponse("Hello World content!"));
        }
    }

当前NSwag不支持使用WithOpenApi()扩展设置 Summary & Description 需要使用[QuickApiSummary] 设置.
RicoSuter/NSwag#3802

[vipwan]

    [QuickApi("world2", Group = "hello", Verbs = Verb.POST)]
    [QuickApiSummary("this is summary", "this is description")]
    public class Hello2Api : BaseQuickApi<HelloApiRequest, HelloApiResponse>
    {
        public override async Task<HelloApiResponse> ExecuteAsync(HelloApiRequest request)
        {
            await Task.CompletedTask;
            return new HelloApiResponse
            {
                Message = $"Hello {request.Name}  {request.Alias} ",
                Alias = $"{request.Alias} {request.HelloService.Hello(request.Name)} " //别名测试 Alias -> a
            };
        }
       
        public override RouteHandlerBuilder HandlerBuilder(RouteHandlerBuilder builder)
        {
            //如果请求是POST,可以添加Example.否则会忽略
            builder.WithExample(new HelloApiRequest
            {
                Name = "vipwan",
                Alias = "alias",
                Q = "q54543534",
                UserName = "u545435",
                Password = "p234565",
            });
            return base.HandlerBuilder(builder);
        }
    }

提供 WithExample()扩展,用于兼容 NSwag的 RequestBody.ActualSchema.Example

[vipwan]

How to Use

1. Step 1

//swagger
builder.Services.AddQuickApiDocument(options =>
{
    options.UseControllerSummaryAsTagDescription = true;
    options.PostProcess = document =>
    {
        document.Info = new OpenApiInfo
        {
            Version = "Quick API Demo V1",
            Title = "Quick API Demo",
            Description = "Biwen.QuickApi Demo",
            TermsOfService = "https://github.com/vipwan",
            Contact = new OpenApiContact
            {
                Name = "Contact Me",
                Url = "https://github.com/vipwan/Biwen.QuickApi"
            },
            License = new OpenApiLicense
            {
                Name = "MIT License",
                Url = "https://github.com/vipwan/Biwen.QuickApi/blob/master/LICENSE.txt"
            }
        };
    };
},
new SecurityOptions()); //提供UI Authorization支持

2. Step 2

//swagger
app.UseQuickApiSwagger();

[vipwan]

提供内置验证器对NSwag的支持!

[vipwan]

请注意 NSwag和WithOpenApi()兼容问题,如果传参需要描述信息 不可使用

.WithOpenApi(generatedOperation =>
{
var parameter = generatedOperation.Parameters[0];
parameter.Description = "The ID associated with the created Todo";
return generatedOperation;
});

请使用 : [Description]:

    public class MyRequest : BaseRequest<MyRequest>
    {
        /// <summary>
        /// 别名测试
        /// </summary>
        [AliasAs("a")]
        [Description("别名测试使用:a")]
        public string? Alias { get; set; }

        [FromQuery]
        [Description("测试FromQuery:Q")]
        public string? Q { get; set; }

        [FromKeyedServices("hello")]
        public HelloService HelloService { get; set; }
    }

[vipwan]

支持使用[DefaultValue]标注默认值

    public abstract class AuthRequest<T> : BaseRequest<T> where T : class, new()
    {
        [Description("登录用户名")]
        [DefaultValue("vipwan@ms.co.ltd")]
        public string? UserName { get; set; }

        [Description("登录密码")]
        public string? Password { get; set; }
    }

[vipwan]

EndpointGroupName支持. 当前支持多文档的情况下EndpointGroupName将非常有用

QuickApi 支持 [EndpointGroupName]特性标注,以及HandlerBuilder.WithGroupName().

    [QuickApi("endpointgroup")]
    [QuickApiSummary("分组测试", "分组测试")]
    [EndpointGroupName("group1")]
    public class EndpointGroupApi : BaseQuickApi
    {
        public override Task<EmptyResponse> ExecuteAsync(EmptyRequest request)
        {
            return Task.FromResult(EmptyResponse.New);
        }
        public override RouteHandlerBuilder HandlerBuilder(RouteHandlerBuilder builder)
        {
            builder.WithTags("group");
            //builder.WithGroupName("group1");
            return base.HandlerBuilder(builder);
        }
    }

如果需要批量设置, 比如路由Group下:

var apis = app.MapBiwenQuickApis();
var groupAdmin = apis.FirstOrDefault(x => x.Group == "admin");
groupAdmin.RouteGroupBuilder?
    .WithTags("authorization")         //自定义Tags
    .WithGroupName("admin")        //自定义EndpointGroupName
    ;

[vipwan]

如果接口过时可以标记 : QuickApiSummaryAttribute 或者 ObsoleteAttribute

    [QuickApi("world5", Verbs = Verb.GET)]
    [QuickApiSummary("过期测试", "过期测试",IsDeprecated =true)]
    [Obsolete("过期测试",false)]
    public class Hello5Api : BaseQuickApi
    {
        public override async Task<EmptyResponse> ExecuteAsync(EmptyRequest request)
        {
            await Task.CompletedTask;
            return EmptyResponse.New;
        }
    }