C# (WebApi)整合 Swagger

JagTom 2024-07-19 11:33:01 阅读 56

SpringBoot-整合Swagger_jboot整合swagger-CSDN博客

C# webapi 也可以整合Swagger

webapi运行其实有个自带的HELP页面

但是如果觉得UI不好看,且没办法显示方法注释等不方便的操作,我们也可以整合Swagger

一、使用NuGet控制台安装Swagger

在菜单中选择工具->NuGet包管理器->程序包管理器控制台 输入指令

<code>Install-Package Swashbuckle

安装成功就已经可以访问页面了

直接运行项目:IP地址:端口号+swagger/ui/index 即可浏览成功。但是会发现页面是英文的且注释无法显示。

二、配置Swagger 显示中文且显示注释

安装完Swagger会在App_Start文件夹下自动生成  SwaggerConfig.cs  更新它

using System.Web.Http;

using WebActivatorEx;

using TPGYWebAPI;

using Swashbuckle.Application;

using TPGYWebAPI.App_Start;

using System.Linq;

using System.Reflection;

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

namespace TPGYWebAPI

{

public class SwaggerConfig

{

public static void Register()

{

var thisAssembly = typeof(SwaggerConfig).Assembly;

GlobalConfiguration.Configuration

.EnableSwagger(c =>

{

c.SingleApiVersion("v1", "TPGYWebAPI");

//添加下述代码

//注意这里的xml文件名要改成你自己的!!!!

var xmlFile = string.Format("{0}/bin/TPGYWebAPI.XML", System.AppDomain.CurrentDomain.BaseDirectory);

if (System.IO.File.Exists(xmlFile))

{

c.IncludeXmlComments(xmlFile);

}

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

c.CustomProvider((defaultProvider) => new SwaggerControllerDescProvider(defaultProvider, xmlFile));

})

.EnableSwaggerUi(b =>

{ //注意这里的路径 项目名要改成你自己的!!!

b.InjectJavaScript(Assembly.GetExecutingAssembly(), "TPGYWebAPI.Scripts.SwaggerConfig.js");

});

}

}

}

并且在该文件夹下创建   SwaggerControllerDescProvider.cs

using Swashbuckle.Swagger;

using System.Collections.Concurrent;

using System.Collections.Generic;

using System.IO;

using System.Linq;

using System.Web;

using System.Xml;

namespace TPGYWebAPI.App_Start

{

/// <summary>

/// Swagger 配置信息

/// </summary>

public class SwaggerControllerDescProvider : ISwaggerProvider

{

private readonly ISwaggerProvider _swaggerProvider;

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

private readonly string _xml;

/// <summary>

///

/// </summary>

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

/// <param name="xml">xml文档路径</param>code>

public SwaggerControllerDescProvider(ISwaggerProvider swaggerProvider, string xml)

{

_swaggerProvider = swaggerProvider;

_xml = xml;

}

/// <summary>

/// GetSwagger

/// </summary>

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

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

/// <returns></returns>

public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)

{

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

SwaggerDocument srcDoc = null;

//只读取一次

if (!_cache.TryGetValue(cacheKey, out 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>

public ConcurrentDictionary<string, string> GetControllerDesc()

{

string xmlpath = _xml;

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

if (File.Exists(xmlpath))

{

XmlDocument xmldoc = new XmlDocument();

xmldoc.Load(xmlpath);

string type = string.Empty, path = string.Empty, controllerName = string.Empty;

string[] arrPath;

int length = -1, cCount = "Controller".Length;

XmlNode summaryNode = null;

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

{

type = node.Attributes["name"].Value;

if (type.StartsWith("T:"))

{

//控制器

arrPath = type.Split('.');

length = arrPath.Length;

controllerName = arrPath[length - 1];

if (controllerName.EndsWith("Controller"))

{

//获取控制器注释

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下面新建SwaggerConfig.js 

<code>'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();

});

 并且把文件属性设置为:

同时还需要启用生成xml文档,右击项目文件属性->生成选项卡(勾选XML文件)。保存后,重新生成。如下图所示

参考文章:  这两篇文章里面都有些瑕疵错误,我进行了修改。总结就是注意 路径问题ASP.NET WEB API 最全的Swagger 安装配置与使用(一) - 我是小柒 - 博客园 (cnblogs.com) 

Swagger使用方法详解(WebApi)——看完不会用你打我_webapi swagger-CSDN博客 



声明

本文内容仅代表作者观点,或转载于其他网站,本站不以此文作为商业用途
如有涉及侵权,请联系本站进行删除
转载本站原创文章,请注明来源及作者。