【swagger】C#中swagger的使用及避坑

@⽬录

开发 web api 的时候，写⽂档是个痛苦的事情，⽽没有⽂档别⼈就不知道怎么调⽤，所以⼜不得不写。swagger 可以⾃动⽣成接⼝⽂档，并测试接⼝，极⼤的了程序员的⽣产⼒。

1 安装

通过 NuGet 安装 Swashbuckle。

安装完成后，App_Start ⽂件夹下会多出⼀个 SwaggerConfig.cs ⽂件。

重新⽣成并发布 api，打开⽹页 host）⽹页显⽰如下：

2 修改名称和版本号

上图中框出的名称和版本号是可以修改的，打开 SwaggerConfig.cs ⽂件，找到如下代码：

c.SingleApiVersion(\"v1\

修改其中的参数，重新发布即可。

3 显⽰说明

swagger 可以读取代码中的注释，并显⽰在⽹页上。如此⼀来，我们只需要在代码中将注释写好，就可以⽣成⼀份可供他⼈阅读的 API ⽂档了。swagger 是通过编译时⽣成的 xml ⽂件来读取注释的。这个 xml ⽂件默认是不⽣成的，所以先要修改配置。第⼀步： 右键项⽬ -> 属性 -> ⽣成，把 XML ⽂档⽂件勾上。

第⼆步： 添加配置

在 SwaggerConfig.cs ⽂件中添加配置如下：

GlobalConfiguration.Configuration .EnableSwagger(c => {

c.SingleApiVersion(\"v2\测试 API 接⼝⽂档\"); // 配置 xml ⽂件路径

c.IncludeXmlComments($@\"{System.AppDomain.CurrentDomain.BaseDirectory}\\bin\\API.Test.xml\"); })

注意：发布的时候，XML ⽂件不会⼀起发布，需要⼿动拷到发布⽬录下。

4 显⽰控制器注释及汉化

默认是不会显⽰控制器注释的，需要⾃⼰写。

在 App_Start 中新建类 SwaggerControllerDescProvider，代码如下：

///

public class SwaggerCacheProvider : ISwaggerProvider{

private readonly ISwaggerProvider _swaggerProvider;

private static ConcurrentDictionary _cache = new ConcurrentDictionary(); private readonly string _xmlPath;

///

/// /// xml⽂档路径

public SwaggerCacheProvider(ISwaggerProvider swaggerProvider, string xmlpath) {

_swaggerProvider = swaggerProvider; _xmlPath = xmlpath; }

public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)

{

var cacheKey = string.Format(\"{0}_{1}\ //只读取⼀次

if (!_cache.TryGetValue(cacheKey, out SwaggerDocument srcDoc)) {

srcDoc = _swaggerProvider.GetSwagger(rootUrl, apiVersion); srcDoc.vendorExtensions = new Dictionary {

{ \"ControllerDesc\ };

_cache.TryAdd(cacheKey, srcDoc); }

return srcDoc; }

///

/// 所有控制器描述

public ConcurrentDictionary GetControllerDesc() {

ConcurrentDictionary controllerDescDict = new ConcurrentDictionary(); if (File.Exists(_xmlPath)) {

XmlDocument xmldoc = new XmlDocument(); xmldoc.Load(_xmlPath);

string[] arrPath;

int cCount = \"Controller\".Length;

foreach (XmlNode node in xmldoc.SelectNodes(\"//member\")) {

string type = node.Attributes[\"name\"].Value; if (type.StartsWith(\"T:\")) {

arrPath = type.Split('.');

string controllerName = arrPath[arrPath.Length - 1]; if (controllerName.EndsWith(\"Controller\")) //控制器 {

//获取控制器注释

XmlNode summaryNode = node.SelectSingleNode(\"summary\");

string key = controllerName.Remove(controllerName.Length - cCount, cCount);

if (summaryNode != null && !string.IsNullOrEmpty(summaryNode.InnerText) && !controllerDescDict.ContainsKey(key)) {

controllerDescDict.TryAdd(key, summaryNode.InnerText.Trim()); } } } } }

return controllerDescDict; }}

另外，新建 swagger.js ⽂件并将其设置成 嵌⼊的资源，这个⽂件的作⽤就是显⽰控制器注释及汉化。js 代码如下：

'use strict';

window.SwaggerTranslator = { _words: [],

translate: function () { var $this = this;

$('[data-sw-translate]').each(function () {

$(this).html($this._tryTranslate($(this).html())); $(this).val($this._tryTranslate($(this).val()));

$(this).attr('title', $this._tryTranslate($(this).attr('title'))); }); },

setControllerSummary: function () { $.ajax({

type: \"get\ async: true,

url: $(\"#input_baseUrl\").val(), dataType: \"json\

success: function (data) {

var summaryDict = data.ControllerDesc; var id, controllerName, strSummary;

$(\"#resources_container .resource\").each(function (i, item) { id = $(item).attr(\"id\"); if (id) {

controllerName = id.substring(9);

strSummary = summaryDict[controllerName]; if (strSummary) {

$(item).children(\".heading\").children(\".options\").first().prepend('

_tryTranslate: function (word) {

return this._words[$.trim(word)] !== undefined ? this._words[$.trim(word)] : word; },

learn: function (wordsMap) { this._words = wordsMap; }};

/* jshint quotmark: double */

window.SwaggerTranslator.learn({

\"Warning: Deprecated\": \"警告：已过时\

\"Implementation Notes\": \"实现备注\ \"Response Class\": \"响应类\ \"Status\": \"状态\

\"Parameters\": \"参数\ \"Parameter\": \"参数\ \"Value\": \"值\

\"Description\": \"描述\

\"Parameter Type\": \"参数类型\ \"Data Type\": \"数据类型\

\"Response Messages\": \"响应消息\ \"HTTP Status Code\": \"HTTP 状态码\ \"Reason\": \"原因\

\"Response Model\": \"响应模型\ \"Request URL\": \"请求 URL\ \"Response Body\": \"响应体\ \"Response Code\": \"响应码\ \"Response Headers\": \"响应头\ \"Hide Response\": \"隐藏响应\ \"Headers\": \"头\

\"Try it out!\": \"试⼀下！\ \"Show/Hide\": \"显⽰/隐藏\ \"List Operations\": \"显⽰操作\ \"Expand Operations\": \"展开操作\ \"Raw\": \"原始\

\"can't parse JSON. Raw result\": \"⽆法解析 JSON。原始结果\ \"Model Schema\": \"模型架构\ \"Model\": \"模型\ \"apply\": \"应⽤\

\"Username\": \"⽤户名\ \"Password\": \"密码\

\"Terms of service\": \"服务条款\ \"Created by\": \"创建者\

\"See more at\": \"查看更多：\

\"Contact the developer\": \"联系开发者\ \"api version\": \"api 版本\

\"Response Content Type\": \"响应 Content Type\ \"fetching resource\": \"正在获取资源\

\"fetching resource list\": \"正在获取资源列表\ \"Explore\": \"浏览\

\"Show Swagger Petstore Example Apis\": \"显⽰ Swagger Petstore ⽰例 Apis\

\"Can't read from server. It may not have the appropriate access-control-origin settings.\": \"⽆法从服务器读取。可能没有正确设置 access-control-origin。\ \"Please specify the protocol for\": \"请指定协议：\

\"Can't read swagger JSON from\": \"⽆法读取 swagger JSON于\

\"Finished Loading Resource Information. Rendering Swagger UI\": \"已加载资源信息。正在渲染 Swagger UI\ \"Unable to read api\": \"⽆法读取 api\ \"from path\": \"从路径\

\"server returned\": \"服务器返回\"});

$(function () {

window.SwaggerTranslator.translate();

window.SwaggerTranslator.setControllerSummary();});

在 SwaggerConfig.cs 添加如下配置：

GlobalConfiguration.Configuration .EnableSwagger(c => {

c.CustomProvider((defaultProvider) => new SwaggerCacheProvider(defaultProvider, $@\"{System.AppDomain.CurrentDomain.BaseDirectory}\\bin\\API.Test.xml\")); })

.EnableSwaggerUi(c => {

c.InjectJavaScript(System.Reflection.Assembly.GetExecutingAssembly(), \"API.Test.swagger.js\"); });

5 路由相同，查询参数不同的⽅法

在实际的 ASP.NET Web API 中，是可以存在 路由相同，HTTP ⽅法相同，查询参数不同 的⽅法的，但不好意思，swagger 中不⽀持，并且会直接报错。如下代码，

[Route(\"api/users\")]

public IEnumerable Get(){

return users;}

[Route(\"api/users\")]

public IEnumerable Get(int sex){

return users;}

报错： Multiple operations with path 'api/users' and method 'GET'.

可以在 SwaggerConfig.cs 添加如下配置：

GlobalConfiguration.Configuration .EnableSwagger(c => {

c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First()); })

此配置的意思是，当遇到此种情况时，取第⼀个⽅法展⽰。

这可以避免报错，但多个⽅法只会在 swagger 中展⽰⼀个。治标不治本，不推荐。所以唯⼀的解决⽅案就是设置成不同的路由。不知道这个问题在之后的版本中会不会修复。

6 忽略 Model 中的某些字段

如下图，新建⽤户时，后台需要⼀个 User 类作为参数。点击右侧的 Model，可以显⽰ User 类的属性及注释。

但是，有些字段其实是⽆需调⽤者传递的。例如 State，调⽤者⽆需知道这些字段的存在。给这些属性标记上 [Newtonsoft.Json.JsonIgnore] 特性，swagger 中不再显⽰了。

当然这种做法也是有缺点的，因为 web api 在返回数据时，调⽤的默认序列化⽅法也是 Newtonsoft.Json 序列化。

7 传递 header

调⽤ api 时，有些信息是放在 HTTP Header 中的，例如 token。这个 swagger 也是⽀持的。新建⼀个特性：

public class ApiAuthorizeAttribute : Attribute{}

新建⼀个类代码如下：

public class AuthorityHttpHeaderFilter : IOperationFilter{

public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) {

if (operation.parameters == null)

operation.parameters = new List(); //判断是否添加权限过滤器

var isAuthorized = apiDescription.ActionDescriptor.GetCustomAttributes().Any(); if (isAuthorized) {

operation.parameters.Add(new Parameter { name = \"token\令牌\ } }}

这段代码就是告诉 swagger，如果遇到的⽅法上标记了 ApiAuthorizeAttribute 特性，则添加⼀个名为 token 的参数在 header 中。最后需要在 SwaggerConfig.cs 中注册这个过滤器。

GlobalConfiguration.Configuration .EnableSwagger(c => {

c.OperationFilter(); })

效果如下：

8 出错时的 HTTP 状态码

我们在⽅法中返回⼀个 400

[Route(\"api/users\")]

public HttpResponseMessage Post([FromBody]User user){

return new HttpResponseMessage() {

Content = new StringContent(\"新建⽤户出错\ StatusCode = HttpStatusCode.BadRequest };}

可是，swagger 中返回的状态码却是 0。

这是因为 Content 指定了 JSON 格式，但传⼊的 content ⼜不是 JSON 格式的。将 content 改为 JSON 格式，或者将 mediaType 改成 text/plain 就可以了。