Merge pull request #222 from EzrealJ/master

add docs files

Author: xljiulang

docs/Readme.md

@@ -0,0 +1,30 @@
+---
+home: true
+heroImage: /logo.png
+heroText: WebApiClient
+tagline: 使用C#接口描述你的http接口
+actions:
+  - text: 快速开始 💡
+    link: /guide/
+    type: primary
+  - text: 安装
+    link: /reference/nuget
+    type: default
+  - text: 旧版文档
+    link: /old/
+    type: default
+features:
+  - title: AOT/JIT
+    details: ⛳ 支持编译时，运行时生成代理类，提高运行时性能和兼容性
+  - title: 多样序列化
+    details: 🛠 默认System.Text.Json,Newtonsoft.Json，同样也支持XML处理
+  - title: 语法分析
+    details: 💡提供接口声明的语法分析与提示，帮助开发者声明接口时避免使用不当的语法。
+  - title: 功能完备
+    details: 🌳支持多种拦截器和过滤器、日志、重试、缓存、异常处理功能
+  - title: 快速接入
+    details: ✒ 支持OAuth2与token管理扩展包，方便实现身份认证和授权
+  - title: 自动生成
+    details: 💻 支持将本地或远程OpenApi文档解析生成WebApiClientCore接口代码的dotnet tool，简化接口声明的工作量
+footer: MIT Licensed | Copyright © WebApiClient
+---

docs/guide/attribute.md

@@ -0,0 +1,65 @@
+
+# 常用内置特性
+
+内置特性指框架内提供的一些特性，拿来即用就能满足一般情况下的各种应用。当然，开发者也可以在实际应用中，编写满足特定场景需求的特性，然后将自定义特性修饰到接口、方法或参数即可。
+
+> 执行前顺序
+
+参数值验证 -> IApiActionAttribute -> IApiParameterAttribute -> IApiReturnAttribute -> IApiFilterAttribute
+
+> 执行后顺序
+
+IApiReturnAttribute -> 返回值验证 -> IApiFilterAttribute
+
+## Return特性
+
+特性名称 | 功能描述 | 备注
+---|---|---|
+RawReturnAttribute | 处理原始类型返回值 | 缺省也生效
+JsonReturnAttribute | 处理Json模型返回值 | 缺省也生效
+XmlReturnAttribute | 处理Xml模型返回值 | 缺省也生效
+NoneReturnAttribute | 处理空返回值 | 缺省也生效
+
+## 常用Action特性
+
+特性名称 | 功能描述 | 备注
+---|---|---|
+HttpHostAttribute | 请求服务http绝对完整主机域名| 优先级比Options配置低
+HttpGetAttribute | 声明Get请求方法与路径| 支持null、绝对或相对路径
+HttpPostAttribute | 声明Post请求方法与路径| 支持null、绝对或相对路径
+HttpPutAttribute | 声明Put请求方法与路径| 支持null、绝对或相对路径
+HttpDeleteAttribute | 声明Delete请求方法与路径| 支持null、绝对或相对路径
+*HeaderAttribute* | 声明请求头 | 常量值
+*TimeoutAttribute* | 声明超时时间 | 常量值
+*FormFieldAttribute* | 声明Form表单字段与值 | 常量键和值
+*FormDataTextAttribute* | 声明FormData表单字段与值 | 常量键和值
+
+## 常用Parameter特性
+
+特性名称 | 功能描述 | 备注
+---|---|---|
+PathQueryAttribute | 参数值的键值对作为url路径参数或query参数的特性 | 缺省特性的参数默认为该特性
+FormContentAttribute | 参数值的键值对作为x-www-form-urlencoded表单 |
+FormDataContentAttribute | 参数值的键值对作为multipart/form-data表单 |
+JsonContentAttribute | 参数值序列化为请求的json内容 |
+XmlContentAttribute | 参数值序列化为请求的xml内容 |
+UriAttribute | 参数值作为请求uri | 只能修饰第一个参数
+ParameterAttribute | 聚合性的请求参数声明 | 不支持细颗粒配置
+*HeaderAttribute* | 参数值作为请求头 |
+*TimeoutAttribute* | 参数值作为超时时间 | 值不能大于HttpClient的Timeout属性
+*FormFieldAttribute* | 参数值作为Form表单字段与值 | 只支持简单类型参数
+*FormDataTextAttribute* | 参数值作为FormData表单字段与值 | 只支持简单类型参数
+
+## Filter特性
+
+特性名称 | 功能描述| 备注
+---|---|---|
+ApiFilterAttribute | Filter特性抽象类 |
+LoggingFilterAttribute | 请求和响应内容的输出为日志的过滤器 |
+
+## 自解释参数类型
+
+类型名称 | 功能描述 | 备注
+---|---|---|
+FormDataFile | form-data的一个文件项 | 无需特性修饰，等效于FileInfo类型
+JsonPatchDocument | 表示将JsonPatch请求文档 | 无需特性修饰

docs/guide/config.md

@@ -0,0 +1,51 @@
+# 配置
+
+## 全局配置
+
+2.0以后的版本，提供services.AddWebApiClient()的全局配置功能，支持提供自定义的IHttpApiActivator<>、IApiActionDescriptorProvider、IApiActionInvokerProvider和IResponseCacheProvider。
+
+## 接口注册与选项
+
+调用`services.AddHttpApi<IUserApi>()`即可完成接口注册，
+每个接口的选项对应为`HttpApiOptions`，选项名称通过HttpApi.GetName()方法获取得到。
+
+## 在IHttpClientBuilder配置
+
+```csharp
+services
+    .AddHttpApi<IUserApi>()
+    .ConfigureHttpApi(Configuration.GetSection(nameof(IUserApi)))
+    .ConfigureHttpApi(o =>
+    {
+        // 符合国情的不标准时间格式，有些接口就是这么要求必须不标准
+        o.JsonSerializeOptions.Converters.Add(new JsonDateTimeConverter("yyyy-MM-dd HH:mm:ss"));
+    });
+```
+
+配置文件的json
+
+```json
+{
+  "IUserApi": {
+    "HttpHost": "http://www.webappiclient.com/",
+    "UseParameterPropertyValidate": false,
+    "UseReturnValuePropertyValidate": false,
+    "JsonSerializeOptions": {
+      "IgnoreNullValues": true,
+      "WriteIndented": false
+    }
+  }
+}
+```
+
+## 在IServiceCollection配置
+
+```csharp
+services
+    .ConfigureHttpApi<IUserApi>(Configuration.GetSection(nameof(IUserApi)))
+    .ConfigureHttpApi<IUserApi>(o =>
+    {
+        // 符合国情的不标准时间格式，有些接口就是这么要求必须不标准
+        o.JsonSerializeOptions.Converters.Add(new JsonDateTimeConverter("yyyy-MM-dd HH:mm:ss"));
+    });
+```

docs/guide/core-analyzers.md

@@ -0,0 +1,6 @@
+# 编译时语法分析
+
+WebApiClientCore.Analyzers提供接口声明的语法分析与提示，帮助开发者声明接口时避免使用不当的语法。
+
+* 1.x版本，接口继承IHttpApi才获得语法分析提示
+* 2.0以后的版本，不继承IHttpApi也获得语法分析提示

docs/guide/data-validation.md

@@ -0,0 +1,34 @@
+# 数据验证
+
+## 参数值验证
+
+对于参数值，支持ValidationAttribute特性修饰来验证值。
+
+```csharp
+public interface IUserApi
+{
+    [HttpGet("api/users/{email}")]
+    Task<User> GetAsync([EmailAddress, Required] string email);
+}
+```
+
+## 参数或返回模型属性验证
+
+```csharp
+public interface IUserApi
+{
+    [HttpPost("api/users")]
+    Task<User> PostAsync([Required][XmlContent] User user);
+}
+
+public class User
+{
+    [Required]
+    [StringLength(10, MinimumLength = 1)]
+    public string Account { get; set; }
+
+    [Required]
+    [StringLength(10, MinimumLength = 1)]
+    public string Password { get; set; }
+}
+```

docs/guide/deformed-interface.md

@@ -0,0 +1,132 @@
+# 适配畸形接口
+
+在实际应用场景中，常常会遇到一些设计不标准的畸形接口，主要是早期还没有restful概念时期的接口，我们要区分分析这些接口，包装为友好的客户端调用接口。
+
+## 不友好的参数名别名
+
+例如服务器要求一个Query参数的名字为`field-Name`，这个是c#关键字或变量命名不允许的，我们可以使用`[AliasAsAttribute]`来达到这个要求：
+
+```csharp
+public interface IDeformedApi
+{
+    [HttpGet("api/users")]
+    ITask<string> GetAsync([AliasAs("field-Name")] string fieldName);  
+}
+```
+
+然后最终请求uri变为api/users/?field-name=`fileNameValue`
+
+## Form的某个字段为json文本
+
+字段 | 值
+---|---
+field1 | someValue
+field2 | {"name":"sb","age":18}
+
+对应强类型模型是
+
+```csharp
+class Field2
+{
+    public string Name {get; set;}
+    
+    public int Age {get; set;}
+}
+```
+
+常规下我们得把field2的实例json序列化得到json文本，然后赋值给field2这个string属性，使用[JsonFormField]特性可以轻松帮我们自动完成Field2类型的json序列化并将结果字符串作为表单的一个字段。
+
+```csharp
+public interface IDeformedApi
+{
+    Task PostAsync([FormField] string field1, [JsonFormField] Field2 field2)
+}
+```
+
+## Form提交嵌套的模型
+
+字段 | 值
+---|---|
+|filed1 |someValue|
+|field2.name | sb|
+|field2.age | 18|
+
+其对应的json格式为
+
+```json
+{
+    "field1" : "someValue",
+    "filed2" : {
+        "name" : "sb",
+        "age" : 18
+    }
+}
+```
+
+合理情况下，对于复杂嵌套结构的数据模型，应当使用applicaiton/json，但接口要求必须使用Form提交，我可以配置KeyValueSerializeOptions来达到这个格式要求：
+
+```csharp
+services.AddHttpApi<IDeformedApi>(o =>
+{
+    o.KeyValueSerializeOptions.KeyNamingStyle = KeyNamingStyle.FullName;
+});
+```
+
+## 响应未指明ContentType
+
+明明响应的内容肉眼看上是json内容，但服务响应头里没有ContentType告诉客户端这内容是json，这好比客户端使用Form或json提交时就不在请求头告诉服务器内容格式是什么，而是让服务器猜测一样的道理。
+
+解决办法是在Interface或Method声明`[JsonReturn]`特性，并设置其EnsureMatchAcceptContentType属性为false，表示ContentType不是期望值匹配也要处理。
+
+```csharp
+[JsonReturn(EnsureMatchAcceptContentType = false)] 
+public interface IDeformedApi 
+{
+}
+```
+
+## 类签名参数或apikey参数
+
+例如每个请求的url额外的动态添加一个叫sign的参数，这个sign可能和请求参数值有关联，每次都需要计算。
+
+我们可以自定义ApiFilterAttribute来实现自己的sign功能，然后把自定义Filter声明到Interface或Method即可
+
+```csharp
+class SignFilterAttribute : ApiFilterAttribute
+{
+    public override Task OnRequestAsync(ApiRequestContext context)
+    {
+        var signService = context.HttpContext.ServiceProvider.GetService<SignService>();
+        var sign = signService.SignValue(DateTime.Now);
+        context.HttpContext.RequestMessage.AddUrlQuery("sign", sign);
+        return Task.CompletedTask;
+    }
+}
+
+[SignFilter]
+public interface IDeformedApi 
+{
+    ...
+}
+```
+
+## 表单字段排序
+
+不知道是哪门公司起的所谓的“签名算法”，往往要字段排序等。
+
+```csharp
+class SortedFormContentAttribute : FormContentAttribute
+{
+    protected override IEnumerable<KeyValue> SerializeToKeyValues(ApiParameterContext context)
+    {
+        这里可以排序、加上其它衍生字段等
+        return base.SerializeToKeyValues(context).OrderBy(item => item.Key);
+    }
+}
+
+public interface IDeformedApi
+{
+    [HttpGet("/path")]
+    Task<HttpResponseMessage> PostAsync([SortedFormContent] Model model);
+}
+```

docs/guide/diy-request-response.md

@@ -0,0 +1,59 @@
+
+# 自定义请求内容与响应内容解析
+
+除了常见的xml或json响应内容要反序列化为强类型结果模型，你可能会遇到其它的二进制协议响应内容，比如google的ProtoBuf二进制内容。
+
+## 1 编写相关自定义特性
+
+### 自定义请求内容处理特性
+
+```csharp
+public class ProtobufContentAttribute : HttpContentAttribute
+{
+    public string ContentType { get; set; } = "application/x-protobuf";
+
+    protected override Task SetHttpContentAsync(ApiParameterContext context)
+    {
+        var stream = new MemoryStream();
+        if (context.ParameterValue != null)
+        {
+            Serializer.NonGeneric.Serialize(stream, context.ParameterValue);
+            stream.Position = 0L;
+        }
+
+        var content = new StreamContent(stream);
+        content.Headers.ContentType = new MediaTypeHeaderValue(this.ContentType);
+        context.HttpContext.RequestMessage.Content = content;
+        return Task.CompletedTask;
+    }
+}
+```
+
+### 自定义响应内容解析特性
+
+```csharp
+public class ProtobufReturnAttribute : ApiReturnAttribute
+{
+    public ProtobufReturnAttribute(string acceptContentType = "application/x-protobuf")
+        : base(new MediaTypeWithQualityHeaderValue(acceptContentType))
+    {
+    }
+
+    public override async Task SetResultAsync(ApiResponseContext context)
+    {
+        var stream = await context.HttpContext.ResponseMessage.Content.ReadAsStreamAsync();
+        context.Result = Serializer.NonGeneric.Deserialize(context.ApiAction.Return.DataType.Type, stream);
+    }
+}
+```
+
+## 2 应用相关自定义特性
+
+```csharp
+[ProtobufReturn]
+public interface IProtobufApi
+{
+    [HttpPut("/users/{id}")]
+    Task<User> UpdateAsync([Required, PathQuery] string id, [ProtobufContent] User user);
+}
+```