.NET Core 3.0 使用Nswag生成Api文档和客户端代码

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

摘要

在前后端分离、Restful API盛行的年代,完美的接口文档,成了交流的纽带。在项目中引入Swagger (也称为OpenAPI),是种不错的选择,它可以让接口数据可视化。下文将会演示

  • 利用Nswag如何生成Api文档

  • 利用NSwagStudio如何生成客户端代码,并且进行测试

什么是 Swagger/OpenAPI?

Swagger 是一个与语言无关的规范,用于描述 REST API。Swagger 项目已捐赠给 OpenAPI 计划,现在它被称为开放 API。这两个名称可互换使用,但 OpenAPI 是首选。它允许计算机和人员了解服务的功能,而无需直接访问实现(源代码、网络访问、文档)。其中一个目标是尽量减少连接取消关联的服务所需的工作量。另一个目标是减少准确记录服务所需的时间。

Nswag VS Swashbuckle?

.NET Swagger 实现类库有两个比较流行:

  • Swashbuckle.AspNetCore 是一个开源项目,用于生成 ASP.NET Core Web API 的 Swagger 文档。

  • NSwag 是另一个用于生成 Swagger 文档并将 Swagger UI 或 ReDoc 集成到 ASP.NET Core Web API 中的开源项目。此外,NSwag 还提供了为 API 生成 C# 和 TypeScript 客户端代码的方法。

 

为什么我在.NET core3.0中选择NSwag呢,NSwag比较活跃,一直在更新,功能也很强大,可以完美的代替Swashbuckle.AspNetCore具体可以参考:https://github.com/aspnet/AspNetCore.Docs/issues/4258

一、利用Nswag生成Api文档

步骤
  1. 创建Asp.NET Core Api项目,并且集成NSwag

  2. 配置项目

  3. 运行项目

创建Asp.NET Core Api项目,并且集成NSwag

我们将简单的创建一个ASP.NET core API项目。将其命名为“WebAPIwithSwg”。基于.NETcore3.0

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

安装nuget包NSwag.AspNetCore

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

接下来,在Startup.cs文件中配置Nswag服务和中间件。

在ConfigureServices方法中添加服务

  public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddSwaggerDocument(); //注册Swagger 服务
        }
在Configure方法中添加Nswag中间件
 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseRouting();
            app.UseAuthorization();
            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
            app.UseOpenApi(); //添加swagger生成api文档(默认路由文档 /swagger/v1/swagger.json)
            app.UseSwaggerUi3();//添加Swagger UI到请求管道中(默认路由: /swagger).
        }
配置项目

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

运行项目

右键项目在浏览器中查看,查看swagger UI需要在url后面添加“/swagger”。本示例http://localhost:54117/swagger

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

二、利用NSwagStudio如何生成客户端代码,并且进行测试
提供GUI界面是NSwag的一大特点,只需要下载安装NSwagStudio,即可生成客户端代码。
步骤
  1. 现在安装NSwagStudio

  2. NSwagStudio配置,生成客户端代码

  3. 创建测试客户端项目

下载安装NSwagStudio

下载NSwag Studio http://rsuter.com/Projects/NSwagStudio/installer.php 安装之后打开 NSwag Studio 如图

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

NSwagStudio配置,生成客户端代码

选择runtime,我选择的是NETCore30,切换OpenAPI/Swagger Specification ,在Specification UR输入你的Swagger.json路径,本示例:http://localhost:54117/swagger/v1/swagger.json输入路径之后,点击 create local copy 按钮获取json。

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

接下配置来生成客户端代码。我们首先选择csharp client”复选框,然后勾选掉 “Inject Http Client via Constructor (life cycle is managed by caller)” ,最后设置下输出路径 点击生成文件(Generate Files)。步骤如下

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

到此客户端代码已经自动生成。

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

查看生成的部分代码


public async System.Threading.Tasks.Task<System.Collections.Generic.ICollection<WeatherForecast>> GetAsync(System.Threading.CancellationToken cancellationToken)
        {
            var urlBuilder_ = new System.Text.StringBuilder();
            urlBuilder_.Append(BaseUrl != null ? BaseUrl.TrimEnd(/) : "").Append("/WeatherForecast");
    
            var client_ = new System.Net.Http.HttpClient();
            try
            {
                using (var request_ = new System.Net.Http.HttpRequestMessage())
                {
                    request_.Method = new System.Net.Http.HttpMethod("GET");
                    request_.Headers.Accept.Add(System.Net.Http.Headers.MediaTypeWithQualityHeaderValue.Parse("application/json"));
    
                    PrepareRequest(client_, request_, urlBuilder_);
                    var url_ = urlBuilder_.ToString();
                    request_.RequestUri = new System.Uri(url_, System.UriKind.RelativeOrAbsolute);
                    PrepareRequest(client_, request_, url_);
    
                    var response_ = await client_.SendAsync(request_, System.Net.Http.HttpCompletionOption.ResponseHeadersRead, cancellationToken).ConfigureAwait(false);
                    try
                    {
                        var headers_ = System.Linq.Enumerable.ToDictionary(response_.Headers, h_ => h_.Key, h_ => h_.Value);
                        if (response_.Content != null && response_.Content.Headers != null)
                        {
                            foreach (var item_ in response_.Content.Headers)
                                headers_[item_.Key] = item_.Value;
                        }
    
                        ProcessResponse(client_, response_);
    
                        var status_ = ((int)response_.StatusCode).ToString();
                        if (status_ == "200") 
                        {
                            var objectResponse_ = await ReadObjectResponseAsync<System.Collections.Generic.ICollection<WeatherForecast>>(response_, headers_).ConfigureAwait(false);
                            return objectResponse_.Object;
                        }
                        else
                        if (status_ != "200" && status_ != "204")
                        {
                            var responseData_ = response_.Content == null ? null : await response_.Content.ReadAsStringAsync().ConfigureAwait(false); 
                            throw new ApiException("The HTTP status code of the response was not expected (" + (int)response_.StatusCode + ").", (int)response_.StatusCode, responseData_, headers_, null);
                        }
            
                        return default(System.Collections.Generic.ICollection<WeatherForecast>);
                    }
                    finally
                    {
                        if (response_ != null)
                            response_.Dispose();
                    }
                }
            }
            finally
            {
                if (client_ != null)
                    client_.Dispose();
            }
        }
创建测试客户端项目

创建一个控制程序项目,命名“WebApiClient”。

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

把自动生成的类“WeatherForecastClient”添加到客户端项目中,然后安装Newtonsoft

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

最后在Main函数中添加测试代码,开始使用Api。

 static async System.Threading.Tasks.Task Main(string[] args)
        {

            var weatherForecastClient = new WeatherForecastClient();
            //gets all values from the API
            var allValues = await weatherForecastClient.GetAsync();
            Console.WriteLine("Hello World!");
        }

运行客户端应用程序,进行调用api

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

当然如果需要调试api项目内部代码,可以设置断点,进入一步一步的调试

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

小结:NSwag 功能远不止这些,本篇文章演示了如何生成api文档和自动生成的api客户端代码方便我们调试,也可以作为对应的sdk。

参考:微软官方文档---https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-2.2&tabs=visual-studio

.NET Core 3.0 使用Nswag生成Api文档和客户端代码

上一篇:如何停止 windows server 2016 系统自动更新


下一篇:好用的Win10快捷键