ASP.NET WEB API Swagger 安装，配置，发布

铁佛  金牌会员 | 2025-1-15 05:12:58 | 显示全部楼层 | 阅读模式
打印 上一主题 下一主题
楼主

主题 877|帖子 877|积分 2631

前言

作为后台的"搬运工"，常常会涉及到一些前后端分离的环境。后端也大多数是使用RESTful 风格的接口。写完之后，就需要使用接口调试工具（postman）给出接口使用实例，还要提供接口说明文档。开辟过程中常常会由于修改代码后文档没有及时更新，造成前端调用报错大概取数不正确等问题。赶巧有一个项目需要新建接口工程，为了避免这样的变乱发现，我发现了Swagger这个架构，可以有效避免这类问题的出现。
Swagger简介

什么是Swagger？



  • Swagger是一个规范且完整的框架，用于天生、描述、调试和可视化Restfull风格的Web服务。它使用一种易于理解的格式提供了 API 的团体概览，帮助开辟职员理解 API 的功能，并于开辟和测试期间与 API 进行交互。
Swagger 优点



  • 可读性和可视化：Swagger 提供了强大的可视化界面，开辟者可以通过 Swagger UI 直接查看 API 的详细内容，包括每个 API 的路径，可担当的参数等等。这使得开辟者更好的理解 API 的工作方式。
  • 以代码为中心的 API 设计：Swagger 允许你以代码为中心来设计 API。这意味着你可以直观地分析和设计你的 API，而不需要切换到其他编辑器或工具。此外，Swagger 默认会提供提示和错误修复，这使得开辟者可以在设计阶段就能找出潜在的错误。
  • 跨平台兼容：Swagger 是跨平台的，可以兼容各种编程语言。
  • 主动文档化：Swagger 可以在开辟时主动天生 API 文档，淘汰了开辟者编写文档的压力。这意味着你可以在编写代码的同时更新开辟文档，确保文档的准确和一致。
上面我个人对Swagger的理解，在 ASP.NET Core 中，已经内置了 Swagger，很方便就能使用。但在 ASP.NET 里，需要我们自己引用和配置才能使用它，下面我们看看 ASP.NET Web Api 怎样使用 Swagger
开辟环境



  • 开辟工具：Visual Studio 2022
  • 使用技能：ASP.NET Web Api
创建Web Api项目




等待项目创建完成之后，解决方案布局如下

使用NuGet控制台安装Swagger

在菜单中选择工具->NuGet包管理器->步伐包管理器控制台 输入指令Install-Package Swashbuckle 选择安装的项目，回车即可。如下图所示：

安装完成后，直接运行项目：IP地址:端口号+swagger/ui/index 即可浏览乐成，如下图：（由于我们创建的是空白的webApi，so没有Controller）

添加Controller


在此我创建了一个DefaultController，代码如下
  1. using System;
  2. using System.Collections.Generic;
  3. using System.Linq;
  4. using System.Net;
  5. using System.Net.Http;
  6. using System.Web.Http;
  7. using WebApplication1.Models;
  9. namespace WebApplication1.Controllers
  10. {
  11.     public class DefaultController : ApiController
  12.     {
  13.         [HttpGet, Route("api/get")]
  14.         public string Get()
  15.         {
  16.             return string.Empty;
  17.         }
  19.         [HttpPost,Route("api/post")]
  20.         public string Post()
  21.         {
  22.             return string.Empty;
  23.         }
  25.         [HttpDelete,Route("api/delete")]
  26.         public string Delete(deleteMode mode)
  27.         {
  28.             return string.Empty;
  29.         }
  31.         [HttpPut,Route("api/put")]
  32.         public string Put()
  33.         {
  34.             return string.Empty;
  35.         }
  37.     }
  38. }
复制代码
添加完Controller之后执行项目，如下图


到此ASP.NET Web Api 添加Swagger，就已经完成了。但是这个页面都是英文，so我们做一下配置添加一下翻译
配置Swagger



  • 在App_Start中配置增加 SwaggerControllerDescProvider.cs 类。代码如下图所示:
  1. using Swashbuckle.Swagger;
  2. using System;
  3. using System.Collections.Concurrent;
  4. using System.Collections.Generic;
  5. using System.IO;
  6. using System.Linq;
  7. using System.Web;
  8. using System.Xml;
  10. namespace WebApplication1.App_Start
  11. {
  12.     /// <summary>
  13.     /// Swagger 配置信息
  14.     /// </summary>
  15.     public class SwaggerControllerDescProvider : ISwaggerProvider
  16.     {
  18.         private readonly ISwaggerProvider _swaggerProvider;
  20.         private static ConcurrentDictionary<string, SwaggerDocument> _cache = new ConcurrentDictionary<string, SwaggerDocument>();
  22.         private readonly string _xml;
  24.         /// <summary>
  25.         ///
  26.         /// </summary>
  27.         /// <param name="swaggerProvider"></param>
  28.         /// <param name="xml">xml文档路径</param>
  29.         public SwaggerControllerDescProvider(ISwaggerProvider swaggerProvider, string xml)
  30.         {
  32.             _swaggerProvider = swaggerProvider;
  34.             _xml = xml;
  36.         }
  40.         /// <summary>
  41.         /// GetSwagger
  42.         /// </summary>
  43.         /// <param name="rootUrl"></param>
  44.         /// <param name="apiVersion"></param>
  45.         /// <returns></returns>
  46.         public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
  47.         {
  48.             var cacheKey = string.Format("{0}_{1}", rootUrl, apiVersion);
  49.             SwaggerDocument srcDoc = null;
  50.             //只读取一次
  51.             if (!_cache.TryGetValue(cacheKey, out srcDoc))
  52.             {
  53.                 srcDoc = _swaggerProvider.GetSwagger(rootUrl, apiVersion);
  54.                 srcDoc.vendorExtensions = new Dictionary<string, object> { { "ControllerDesc", GetControllerDesc() } };
  55.                 _cache.TryAdd(cacheKey, srcDoc);
  57.             }
  59.             return srcDoc;
  61.         }
  65.         /// <summary>
  66.         /// 从API文档中读取控制器描述
  67.         /// </summary>
  68.         /// <returns>所有控制器描述</returns>
  69.         public ConcurrentDictionary<string, string> GetControllerDesc()
  70.         {
  71.             string xmlpath = _xml;
  72.             ConcurrentDictionary<string, string> controllerDescDict = new ConcurrentDictionary<string, string>();
  73.             if (File.Exists(xmlpath))
  74.             {
  75.                 XmlDocument xmldoc = new XmlDocument();
  76.                 xmldoc.Load(xmlpath);
  77.                 string type = string.Empty, path = string.Empty, controllerName = string.Empty;
  78.                 string[] arrPath;
  79.                 int length = -1, cCount = "Controller".Length;
  80.                 XmlNode summaryNode = null;
  81.                 foreach (XmlNode node in xmldoc.SelectNodes("//member"))
  82.                 {
  83.                     type = node.Attributes["name"].Value;
  84.                     if (type.StartsWith("T:"))
  85.                     {
  86.                         //控制器
  87.                         arrPath = type.Split('.');
  88.                         length = arrPath.Length;
  89.                         controllerName = arrPath[length - 1];
  90.                         if (controllerName.EndsWith("Controller"))
  91.                         {
  93.                             //获取控制器注释
  94.                             summaryNode = node.SelectSingleNode("summary");
  95.                             string key = controllerName.Remove(controllerName.Length - cCount, cCount);
  96.                             if (summaryNode != null && !string.IsNullOrEmpty(summaryNode.InnerText) && !controllerDescDict.ContainsKey(key))
  97.                             {
  99.                                 controllerDescDict.TryAdd(key, summaryNode.InnerText.Trim());
  101.                             }
  103.                         }
  105.                     }
  107.                 }
  109.             }
  111.             return controllerDescDict;
  113.         }
  115.     }
  116. }
复制代码


  • 新键Scripts文件夹增加SwaggerConfig.js。如下代码所示：
  1. 'use strict';
  3. window.SwaggerTranslator = {
  5.     _words: [],
  9.     translate: function () {
  11.         var $this = this;
  13.         $('[data-sw-translate]').each(function () {
  15.             $(this).html($this._tryTranslate($(this).html()));
  17.             $(this).val($this._tryTranslate($(this).val()));
  19.             $(this).attr('title', $this._tryTranslate($(this).attr('title')));
  21.         });
  23.     },
  27.     setControllerSummary: function () {
  29.         $.ajax({
  31.             type: "get",
  33.             async: true,
  35.             url: $("#input_baseUrl").val(),
  37.             dataType: "json",
  39.             success: function (data) {
  41.                 var summaryDict = data.ControllerDesc;
  43.                 var id, controllerName, strSummary;
  45.                 $("#resources_container .resource").each(function (i, item) {
  47.                     id = $(item).attr("id");
  49.                     if (id) {
  51.                         controllerName = id.substring(9);
  53.                         strSummary = summaryDict[controllerName];
  55.                         if (strSummary) {
  57.                             $(item).children(".heading").children(".options").first().prepend('<li class="controller-summary" title="' + strSummary + '">' + strSummary + '</li>');
  59.                         }
  61.                     }
  63.                 });
  65.             }
  67.         });
  69.     },
  71.     _tryTranslate: function (word) {
  73.         return this._words[$.trim(word)] !== undefined ? this._words[$.trim(word)] : word;
  75.     },
  79.     learn: function (wordsMap) {
  81.         this._words = wordsMap;
  83.     }
  85. };
  91. /* jshint quotmark: double */
  93. window.SwaggerTranslator.learn({
  95.     "Warning: Deprecated": "警告：已过时",
  97.     "Implementation Notes": "实现备注",
  99.     "Response Class": "响应类",
  101.     "Status": "状态",
  103.     "Parameters": "参数",
  105.     "Parameter": "参数",
  107.     "Value": "值",
  109.     "Description": "描述",
  111.     "Parameter Type": "参数类型",
  113.     "Data Type": "数据类型",
  115.     "Response Messages": "响应消息",
  117.     "HTTP Status Code": "HTTP状态码",
  119.     "Reason": "原因",
  121.     "Response Model": "响应模型",
  123.     "Request URL": "请求URL",
  125.     "Response Body": "响应体",
  127.     "Response Code": "响应码",
  129.     "Response Headers": "响应头",
  131.     "Hide Response": "隐藏响应",
  133.     "Headers": "头",
  135.     "Try it out!": "试一下！",
  137.     "Show/Hide": "显示/隐藏",
  139.     "List Operations": "显示操作",
  141.     "Expand Operations": "展开操作",
  143.     "Raw": "原始",
  145.     "can't parse JSON.  Raw result": "无法解析JSON. 原始结果",
  147.     "Model Schema": "模型架构",
  149.     "Model": "模型",
  151.     "apply": "应用",
  153.     "Username": "用户名",
  155.     "Password": "密码",
  157.     "Terms of service": "服务条款",
  159.     "Created by": "创建者",
  161.     "See more at": "查看更多：",
  163.     "Contact the developer": "联系开发者",
  165.     "api version": "api版本",
  167.     "Response Content Type": "响应Content Type",
  169.     "fetching resource": "正在获取资源",
  171.     "fetching resource list": "正在获取资源列表",
  173.     "Explore": "浏览",
  175.     "Show Swagger Petstore Example Apis": "显示 Swagger Petstore 示例 Apis",
  177.     "Can't read from server.  It may not have the appropriate access-control-origin settings.": "无法从服务器读取。可能没有正确设置access-control-origin。",
  179.     "Please specify the protocol for": "请指定协议：",
  181.     "Can't read swagger JSON from": "无法读取swagger JSON于",
  183.     "Finished Loading Resource Information. Rendering Swagger UI": "已加载资源信息。正在渲染Swagger UI",
  185.     "Unable to read api": "无法读取api",
  187.     "from path": "从路径",
  189.     "server returned": "服务器返回"
  191. });
  193. $(function () {
  195.     window.SwaggerTranslator.translate();
  197.     window.SwaggerTranslator.setControllerSummary();
  199. });
复制代码
注意：添加JS后，将文件设置为“嵌入的资源”。如下：



  • 修改App_Start文件夹中的SwaggerConfig.cs，详细修改代码如下：
  1. using System.Web.Http;
  2. using WebActivatorEx;
  3. using WebApplicationAndSwaggerDemo;
  4. using Swashbuckle.Application;
  5. using System.Linq;
  6. using WebApplication1.App_Start;
  7. using System.Reflection;
  9. [assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]
  11. namespace WebApplicationAndSwaggerDemo
  12. {
  13.     public class SwaggerConfig
  14.     {
  15.         public static void Register()
  16.         {
  17.             var thisAssembly = typeof(SwaggerConfig).Assembly;
  19.             GlobalConfiguration.Configuration
  20.                 .EnableSwagger(c =>
  21.                     {
  22.                         
  23.                         c.SingleApiVersion("v1", "WebApplicationAndSwaggerDemo");
  25.                         //设置接口描述xml路径地址
  26.                         var xmlFile = string.Format("{0}/bin/WebApplicationAndSwaggerDemo..XML", System.AppDomain.CurrentDomain.BaseDirectory);
  27.                         if (System.IO.File.Exists(xmlFile))
  28.                         {
  29.                             c.IncludeXmlComments(xmlFile);
  30.                         }
  31.                         c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
  32.                         c.CustomProvider((defaultProvider) => new SwaggerControllerDescProvider(defaultProvider, xmlFile));
  34.                     })
  35.                 .EnableSwaggerUi(b =>
  36.                     {
  37.                         b.InjectJavaScript(Assembly.GetExecutingAssembly(), "WebApplicationAndSwaggerDemo.Scripts.SwaggerConfig.js");
  38.                     });
  39.         }
  40.     }
  41. }
复制代码
修改项目属性天生XML文件，如下图：

到如今为止，配置已经完成，最终界面。如下图所示：

摆设

在这里我选择 iis 摆设


  • 首老师成摆设文件：项目右击->选择发布->选择文件夹，如下图：

    此时需要修改也可以修改路径，反之默认路劲即可

    点击发布

    看到如图所示字样，表示发布乐成

  • 登录服务器，安装iis，并新建站点，如图所示

  • 发布完成后http://id地址:端口swagger/ui/index，外网访问效果如下图：

竣事语

此文档防止后续忘记简单记录一下。盼望可以帮助到大家，欢迎留言交流 谢谢！

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。

本帖子中包含更多资源

您需要 登录 才可以下载或查看，没有账号？立即注册

x
回复

使用道具 举报

0 个回复

倒序浏览
返回列表

快速回复

高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 or 立即注册

本版积分规则

铁佛

金牌会员
这个人很懒什么都没写!

楼主热帖

标签云

挺好的 服务器
微信订阅号
微信服务号
微信客服
小程序
H5
关于我们 商务合作 网站地图
©Copyright 2022-2024 杭州祥升科技有限公司 版权所有 浙ICP备20004199号
快速回复 返回顶部 返回列表