【西天取经】（骚操作）net core WebAPI生成ReDoc文档后支持多语言样例（x-code-samples）

【西天取经】（骚操作）net core WebAPI生成ReDoc文档后支持多语言样例（x-code-samples）

现在做的项目多是以WebAPI的方式对外提供功能的，配合像Vue这样的前端技术展示出页面、或者自己写的程序调用、或者外部第三方公司写的程序调用。

程序员不仅需要写完接口的功能，还需要把这些接口功能对应的文档写出来，多数情况下程序员会直接通过工具来生成接口的文档，普遍使用的是：Swagger。

.net core使用Swagger功能需要引用Swashbuckle.AspNetCore这个包以及它的子包。（也有用别的包来实现的）。我只介绍我的项目里面用到哪些包：

  <PackageReference Include="Swashbuckle.AspNetCore" Version="5.6.3" />
  <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="5.6.3" />
  <PackageReference Include="Swashbuckle.AspNetCore.Newtonsoft" Version="5.6.3" />
  <PackageReference Include="Swashbuckle.AspNetCore.ReDoc" Version="5.6.3" />

其中Swashbuckle.AspNetCore.ReDoc这个包就是我这篇文章要介绍的内容。ReDoc是一个既美观又大方的展示页面（它使用React+TypeScript语言开发出来的，最终编译后会生成一个js文件和一个html文件），Swashbuckle.AspNetCore.ReDoc包里面已经包含编译之后的js和html文件，如图所示：

没用过ReDoc界面的人可能还是不清楚它到底长什么样子。

首先，看一下Swagger-UI的界面样子：（基本上都见过了）

然后，ReDoc的界面样子：（我要介绍的就是这个界面）

通常情况下，程序员会把Swagger-UI的界面留给自己或者内部使用，因为Swagger-UI可以发送请求测试接口的功能，也是入门必备的技能包；但是ReDoc更侧重于给外部第三方的客户使用，这两种展示方式我个人认为只是有用途上的区分而已。而 Knife4j 和 Swagger-UI 用途上我认为更接近。下图是Knife4j的界面（本文不介绍），我们给前端组的小伙伴提供接口文档用这个界面。

如果想把ReDoc文档变得更漂亮或者想加上公司的logo等等有定制需求时，就需要下载ReDoc源码自己改吧改吧了。我们目前就是自己稍微改了一下然后放到官网上去的。

ReDoc如果只是把上面这些接口的信息显示出来肯定是缺了点什么，到底缺什么呢？答案是：缺例子。第三方客户看到这些文档，又没有例子100%会关闭你的网页，因为没有人会花时间学习你的接口文档，除非你做的项目足够强大或者你所在的公司高大尚。但是往往像这样牛逼的公司提供出来的接口文档都会很全的，相反自己做的接口文档少这少那，又怎么会有人用你做的东西呢？

下面就来做一个带有多语言的sample的Redoc文档，如图所示：

• C#：

•  Java：

 

•  PHP：

 

•  Python：

 

代码奉上：（前提是你的会Swagger，我这里只介绍ReDoc添加多语言sample代码）

1、.net core项目使用ReDoc：

/// <summary>
/// 加入ReDoc中间件
/// </summary>
/// <param name="app"></param>
/// <param name="environment"></param>
private void UseReDoc(IApplicationBuilder app, IWebHostEnvironment environment)
{
    app.UseSwagger(options => { options.RouteTemplate = "webapi/swagger/{documentName}/swagger.yaml"; options.SerializeAsV2 = true; });

    app.UseReDoc(option =>
    {
        option.RoutePrefix = "webapi";
        option.SpecUrl = $"/webapi/swagger/v1/swagger.yaml";
        option.DocumentTitle = "ReDoc多语言sample代码示例";
        option.ConfigObject = new Swashbuckle.AspNetCore.ReDoc.ConfigObject
        {
            NoAutoAuth = true,
            HideDownloadButton = true,
            HideLoading = false,
            HideHostname = true,
            RequiredPropsFirst = true,
            DisableSearch = true,
            NativeScrollbars = true,
        };
    });
}

2、设置ReDoc增加多语言的samples代码，ReDoc就是从x-code-samples里面拿各种语言的sample代码：

/// <summary>
/// 用来生成Swagger里面ReDoc多语言Sample例子。即："x-code-samples"里面的内容
/// </summary>
public class XCodeSamplesOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        const string KEY = "x-code-samples";
        if (!operation.Extensions.ContainsKey(KEY))
        {
            var xCodeSamplesAttributes = context.MethodInfo
                                                .GetCustomAttributes(true)
                                                .OfType<XCodeSamplesAttribute>()  //自定义的Attribute
                                                ;
            if (xCodeSamplesAttributes == null || !xCodeSamplesAttributes.Any())
            {
                return;
            }

            OpenApiArray openApiArray = new OpenApiArray();
            foreach(var xCodeSamples in xCodeSamplesAttributes)
            {
                openApiArray.Add(new OpenApiObject
                   {
                       {"lang", new OpenApiString(xCodeSamples.Lang)},
                       {"source", new OpenApiString(xCodeSamples.Source, true)}
                   });
            }
            operation.Extensions.Add(KEY, openApiArray);
        }
    }
}

3、自定义XCodeSamplesAttribute，用来添加每种语言的sample代码：

/// <summary>
/// 用来生成Swagger里面ReDoc多语言Sample例子。即："x-code-samples"里面的内容
/// </summary>
[System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple = true)]
public class XCodeSamplesAttribute : Attribute
{
    /// <summary>
    /// 语言
    /// </summary>
    public string Lang { get; set; }
    /// <summary>
    /// 代码
    /// </summary>
    public string Source { get; set; }

    public XCodeSamplesAttribute(string lang, string source)
    {
        this.Lang = lang;
        this.Source = source;
    }
}

4、设置Swagger的IOperationFilter和ReDoc进行关联，关于Swagger里面的设置还有很多其他知识，我这里就不啰嗦了，百度、谷歌都能找得到。这里只介绍和多语言sample相关的代码部分：

/// <summary>
/// 注入Swagger服务
/// </summary>
/// <param name="services"></param>
private void AddSwagger(IServiceCollection services)
{
    //注册Swagger生成器
    services.AddSwaggerGen(option =>
    {
    ...
       option.OperationFilter<XCodeSamplesOperationFilter>();
    ...
    }
}

5、给Controller里面的某一个Action上添加多语言的sample代码，使用自定义的XCodeSamplesAttribute（下面的代码看着有点丑）。

/// <summary>
/// 获取单个用户信息
/// </summary>
/// <param name="userId">用户ID</param>
/// <returns></returns>
[HttpGet("{user_id}")]
[XCodeSamples(lang: "C#", source: @"
var client = new RestClient(""https://example.com/webapi/a2/users/{user_id}"");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader(""webapi_token"", ""your secret key"");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);")

 , XCodeSamples(lang: "Java", source: @"
OkHttpClient client = new OkHttpClient().newBuilder().build();
Request request = new Request.Builder()
                     .url(""https://example.com/webapi/a2/users/{user_id}"")
                     .method(""GET"", null)
                     .addHeader(""webapi_token"", ""your secret key"")
                     .build();
Response response = client.newCall(request).execute();")

 , XCodeSamples(lang: "PHP", source: @"
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => ""https://example.com/webapi/a2/users/%7Buser_id%7D"",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => """",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => ""GET"",
CURLOPT_HTTPHEADER => array(
""webapi_token: your secret key""
),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;")

 , XCodeSamples(lang: "Python", source: @"
import http.client
import mimetypes

conn = http.client.HTTPSConnection(""example.com"", 443)
payload = ''
headers = {
'webapi_token': 'your secret key'
}
conn.request(""GET"", ""/webapi/a2/users/{user_id}"", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode(""utf-8""))")
]
public JsonModel<ApiUserInfoModelOpenAPI> GetUser([FromRoute(Name = "user_id")] long userId)
{
    ...
}

好了，终于完工了，这回你的ReDoc文档看起来就很全面了。

如果你不知道其他语言的代码怎么写出来的，我这里介绍一个简单的方法，使用Postman可以帮你轻松完成，我拿一个URL举例来介绍，如图：

从下图里找到你需要添加的语言，然后直接复制右面的代码就可以了。注意：往C#里面粘贴下面的代码时，因为字符串里面会有双引号，和C#里面的@符号有冲突，用两个双引号就可以解决了。

 

希望每一个对外提供接口的项目，都能给你的客户提供更全更好的接口文档。