F66永乐集团首页F66永乐集团首页


F66永乐集团娱乐

swagger文档转换为WebApiClient声明式代码

1 swagger简介

Swagger是一个规范且完整的框架,提供描述、生产、消费和可视化RESTful Web Service。其核心是使用json来规范描述RESTful接口,另外有提供UI来查看接口说明,并有一套生成不同语言的客户端调用代码生成器。

1.1 对Api提供者

自顶向下

使用Swagger编辑器创建Swagger定义,然后使用Swagger代码生成工具生成服务器实现。

自底向上

为已有的REST API创建Swagger定义。一般的,Api提供者都会选择这种方式,比如在asp.net里集成swagger的支持,在写好接口代码之后,访问对应的swagger的访问Uri地址,就可以得到swagger.json。例如:http://petstore.swagger.io/v2/swagger.json

{ "swagger": "2.0", "info": { "tags": null, "description": "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.", "version": "1.0.0", "title": "Swagger Petstore", "termsOfService": "http://swagger.io/terms/", "contact": { "email": "apiteam@swagger.io" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "host": "petstore.swagger.io", "basePath": "/v2", "tags": [ ...

1.2 对Api使用者

使用swagger UI

一些提供者的站点会提供swagger ui来查看其swagger.json,例如:http://petstore.swagger.io/ 有了这些UI,自己手工编写客户端调用代码也非常简单了。

使用Swagger Codegen

可以Swagger Codegen的将swagger.json逆向生成你需要的客户端调用接口代码,本质上是使用了代码模板结合swagger.json描述来生成代码。在.net里,有一个Nswag项目,可以将swagger.json生成使用HttpClient来请求接口的c#代码。但是这些代码的质量也比较差,比如以下代码的HttpClient的生命周期也就无法很好的维护。

/// <summary>Add a new pet to the store</summary>/// <param name="body">Pet object that needs to be added to the store</param>/// <exception cref="SwaggerException">A server side error occurred.</exception>/// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of cancellation.</param>public async System.Threading.Tasks.Task AddPetAsync(Pet body, System.Threading.CancellationToken cancellationToken){ var urlBuilder_ = new System.Text.StringBuilder(); urlBuilder_.Append(BaseUrl != null ? BaseUrl.TrimEnd("/") : "").Append("/pet"); var client_ = new System.Net.Http.HttpClient(); try { using (var request_ = new System.Net.Http.HttpRequestMessage()) { var content_ = new System.Net.Http.StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(body, _settings.Value)); content_.Headers.ContentType = System.Net.Http.Headers.MediaTypeHeaderValue.Parse("application/json"); request_.Content = content_; request_.Method = new System.Net.Http.HttpMethod("POST"); 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_ == "405") { var responseData_ = response_.Content == null ? null : await response_.Content.ReadAsStringAsync().ConfigureAwait(false); throw new SwaggerException("Invalid input", (int)response_.StatusCode, responseData_, headers_, null); } else if (status_ != "200" && status_ != "204") { var responseData_ = response_.Content == null ? null : await response_.Content.ReadAsStringAsync().ConfigureAwait(false); throw new SwaggerException("The HTTP status code of the response was not expected (" + (int)response_.StatusCode + ").", (int)response_.StatusCode, responseData_, headers_, null); } } finally { if (response_ != null) response_.Dispose(); } } } finally { if (client_ != null) client_.Dispose(); }}

2 WebApiClient.tools简介

WebApiClient是.net平台的一款RESTful声明式的面向切面客户端,其几乎100%实现了swagger定义的规范,WebApiClient.tools.swagger旨在将swagger.json逆向生成符合WebApiClient的声明式c#代码。

2.1 作用

使用原生HttpClient,你可能需要20行代码包装调用一个接口;使用WebApiClient,你可能只需要一行代码来定义接口方法;使用WebApiClient + WebApiClient.tools.swagger,你一行代码都不用写。

2.2 工作原理

    使用NSwag解析json得到SwaggerDocument使用RazorEngine将SwaggerDocument传入cshtml模板编译得到html使用AngleSharp将html的文本代码提取,得到WebApiClient的声明式代码代码美化,输出到本地文件

2.3 样例效果

接口代码

/// <summary> /// Everything about your Pets /// </summary> [TraceFilter] [HttpHost("https://petstore.swagger.io/v2/")] public interface IPetApi : IHttpApi { /// <summary> /// Add a new pet to the store /// </summary> /// <param name="body">Pet object that needs to be added to the store</param> [HttpPost("pet")] ITask<HttpResponseMessage> AddPetAsync( [Required] [JsonContent] Pet body ); /// <summary> /// Update an existing pet /// </summary> /// <param name="body">Pet object that needs to be added to the store</param> [HttpPut("pet")] ITask<HttpResponseMessage> UpdatePetAsync( [Required] [JsonContent] Pet body ); ...

模型代码

public class Pet { [AliasAs("id")] public long? Id { get; set; } [AliasAs("category")] public Category Category { get; set; } [AliasAs("name")] [Required(AllowEmptyStrings = true)] public string Name { get; set; } [AliasAs("photoUrls")] [Required] public List<string> PhotoUrls { get; set; } = new List<string>(); ...

3 相关资源

WebApiClient

github: https://github.com/dotnetcore/WebApiClient

WebApiClient.tools

github: https://github.com/xljiulang/WebApiClient.Tools

NSwag

github: https://github.com/RSuter/NSwag

RazorEngine

github: https://github.com/Antaris/RazorEngine

欢迎阅读本文章: 易先志

F66永乐国际首页官网

F66永乐集团娱乐