前言

Swagger 是一个开源的框架，支持 OpenAPI 规范，可以根据 API 规范自动生成美观的、易于浏览的 API 文档页面，包括请求参数、响应示例等信息，并且，Swagger UI 提供了一个交互式的界面，可以帮助我们快速测试和调试 API，验证 API 的功能和正确性。

总的来说，Swagger 是一个强大的工具，可以帮助开发人员设计、构建和文档化 RESTful API，提高 API 的可读性、可维护性和互操作性，有了它，我们就可以更方便、更有效率地管理 API。

在 ASP.NET Core 中，已经内置了 Swagger，很方便就能使用。但在 ASP.NET 里，需要我们自己引用和配置才能使用它，下面通过一个 Step By Step 例子来看看 ASP.NET Web Api 如何使用 Swagger。

Step By Step 步骤

创建 .netframework webapi 项目

在项目上右键 - 项目属性 - 生成 - （输出）勾选 “XML文档文件"并填写自定义路径如"App_Data\apidoc.xml”

Nuget 安装以下 Swagger 相关的两个包

Swashbuckle

Swagger.NET.UI（这个不装也可以）

创建 App_Start/SwaggerCacheProvider 辅助类，用于获取 xml 文件注释内容，留意注释

<code>using Swashbuckle.Swagger;

using System;

using System.Collections.Concurrent;

using System.Collections.Generic;

using System.IO;

using System.Linq;

using System.Web;

using System.Xml;

namespace SwaggerTest

{

/// <summary>

/// 支持方法注释

/// </summary>

public class SwaggerCacheProvider : ISwaggerProvider

{

private readonly ISwaggerProvider _swaggerProvider;

private static ConcurrentDictionary<string, SwaggerDocument> _cache = new ConcurrentDictionary<string, SwaggerDocument>();

private readonly string _xmlPath;

/// <summary>

/// 构造方法

/// </summary>

/// <param name="swaggerProvider"></param>code>

/// <param name="xmlpath"></param>code>

public SwaggerCacheProvider(ISwaggerProvider swaggerProvider, string xmlpath)

{

_swaggerProvider = swaggerProvider;

_xmlPath = xmlpath;

}

/// <summary>

/// 生成 Swagger 文档，并存入缓存

/// </summary>

/// <param name="rootUrl"></param>code>

/// <param name="apiVersion"></param>code>

/// <returns></returns>

/// <exception cref="NotImplementedException"></exception>code>

public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)

{

var cacheKey = string.Format("{0}_{1}", rootUrl, apiVersion);

// 只读取一次

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

{

srcDoc = _swaggerProvider.GetSwagger(rootUrl, apiVersion);

srcDoc.vendorExtensions = new Dictionary<string, object>

{

{ "ControllerDesc", GetControllerDesc() }

};

_cache.TryAdd(cacheKey, srcDoc);

}

return srcDoc;

}

/// <summary>

/// 从API文档中读取控制器描述

/// </summary>

/// <returns></returns>

private ConcurrentDictionary<string, string> GetControllerDesc()

{

ConcurrentDictionary<string, string> controllerDescDict = new ConcurrentDictionary<string, string>();

if (File.Exists(_xmlPath))

{

// 1. 加载生成 xml

XmlDocument xmldoc = new XmlDocument();

xmldoc.Load(_xmlPath);

// 2. 读取控制器方法注释内容

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;

}

}

}

创建 Scripts\swagger.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('<li class="controller-summary" title="' + strSummary + '">' + strSummary + '</li>');code>

}

}

});

}

});

},

_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();

});

右键 Scripts\swagger.js - 属性 - 生成操作 - 改为 “嵌入的资源”

打开并修改 App_Start\SwaggerConfig.cs（安装以上包后自动生成此文件），以下是修改后的完整代码

using System.Web.Http;

using WebActivatorEx;

using SwaggerTest;

using Swashbuckle.Application;

using System.Reflection;

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

namespace SwaggerTest

{

// 完整版 Swagger config 代码

/// <summary>

/// 配置 Swagger

/// </summary>

public class SwaggerConfig

{

/// <summary>

/// 注册

/// </summary>

public static void Register()

{

var thisAssembly = typeof(SwaggerConfig).Assembly;

GlobalConfiguration.Configuration

.EnableSwagger(c =>

{

//用于启用和设置Swagger的配置信息。

c.SingleApiVersion("v2", "测试 API 接口文档");

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

//获取项目指定路径下xml文件

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

})

.EnableSwaggerUi(c =>

{

//用于启用UI界面上的东西。

//加载汉化的js文件，注意 swagger.js文件属性必须设置为“嵌入的资源”。 APIUI.Scripts.swagger.js依次是：项目名称->文件夹->js文件名

c.InjectJavaScript(Assembly.GetExecutingAssembly(), "SwaggerTest.Scripts.swagger.js");

});

}

}

}

打开并注释掉 App_Start\SwaggerNet.cs 代码（安装以上包后自动生成此文件）

using System;

using System.IO;

using System.Web;

using System.Web.Http;

using System.Web.Http.Description;

using System.Web.Http.Dispatcher;

using System.Web.Routing;

using Swagger.Net;

//[assembly: WebActivator.PreApplicationStartMethod(typeof(SwaggerTest.App_Start.SwaggerNet), "PreStart")]

//[assembly: WebActivator.PostApplicationStartMethod(typeof(SwaggerTest.App_Start.SwaggerNet), "PostStart")]

namespace SwaggerTest.App_Start

{

/// <summary>

/// Swagger Net

/// </summary>

public static class SwaggerNet

{

//public static void PreStart()

//{

// RouteTable.Routes.MapHttpRoute(

// name: "SwaggerApi",

// routeTemplate: "api/docs/{controller}",

// defaults: new { swagger = true }

// );

//}

//public static void PostStart()

//{

// var config = GlobalConfiguration.Configuration;

// config.Filters.Add(new SwaggerActionFilter());

// try

// {

// config.Services.Replace(typeof(IDocumentationProvider),

// new XmlCommentDocumentationProvider(HttpContext.Current.Server.MapPath("~/bin/SwaggerTest.XML")));

// }

// catch (FileNotFoundException)

// {

// throw new Exception("Please enable \"XML documentation file\" in project properties with default (bin\\SwaggerTest.XML) value or edit value in App_Start\\SwaggerNet.cs");

// }

//}

}

}

至此，Swagger 配置就完成了，接着就可以运行看看效果了

测试