ASP.NET Web Api 如何使用 Swagger 管理 API

简介: ASP.NET Web Api 如何使用 Swagger 管理 API

前言

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 步骤

  1. 创建 .netframework webapi 项目
  2. 在项目上右键 - 项目属性 - 生成 - (输出)勾选 “XML文档文件"并填写自定义路径如"App_Data\apidoc.xml”
  3. Nuget 安装以下 Swagger 相关的两个包

Swashbuckle

Swagger.NET.UI(这个不装也可以)

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

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>
    /// <param name="xmlpath"></param>
    public SwaggerCacheProvider(ISwaggerProvider swaggerProvider, string xmlpath)
    {
      _swaggerProvider = swaggerProvider;
      _xmlPath = xmlpath;
    }
    /// <summary>
    /// 生成 Swagger 文档,并存入缓存
    /// </summary>
    /// <param name="rootUrl"></param>
    /// <param name="apiVersion"></param>
    /// <returns></returns>
    /// <exception cref="NotImplementedException"></exception>
    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;
    }
  }
}

5.创建 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>');
            }
          }
        });
      }
    });
  },
  _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();
});

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

7.打开并修改 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");
          });
    }
  }
}

8.打开并注释掉 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");
    //    }
    //}
  }
}

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

测试

  • 配置完成后,直接运行项目,打开以下网址,即可看到效果
https://localhost:44335/swagger/

其它

  • Swagger.NET.UI不是必要的,运行 SwaggerUI目录下面的 index 反而会出错

我是老杨,一个奋斗在一线的资深研发老鸟,让我们一起聊聊技术,聊聊人生。

都看到这了,求个点赞、关注、在看三连呗,感谢支持。


相关文章
|
9天前
|
开发框架 监控 前端开发
在 ASP.NET Core Web API 中使用操作筛选器统一处理通用操作
【9月更文挑战第27天】操作筛选器是ASP.NET Core MVC和Web API中的一种过滤器,可在操作方法执行前后运行代码,适用于日志记录、性能监控和验证等场景。通过实现`IActionFilter`接口的`OnActionExecuting`和`OnActionExecuted`方法,可以统一处理日志、验证及异常。创建并注册自定义筛选器类,能提升代码的可维护性和复用性。
|
9天前
|
开发框架 .NET 中间件
ASP.NET Core Web 开发浅谈
本文介绍ASP.NET Core,一个轻量级、开源的跨平台框架,专为构建高性能Web应用设计。通过简单步骤,你将学会创建首个Web应用。文章还深入探讨了路由配置、依赖注入及安全性配置等常见问题,并提供了实用示例代码以助于理解与避免错误,帮助开发者更好地掌握ASP.NET Core的核心概念。
28 3
|
14天前
|
开发框架 前端开发 .NET
VB.NET中如何利用ASP.NET进行Web开发
在VB.NET中利用ASP.NET进行Web开发是一个常见的做法,特别是在需要构建动态、交互式Web应用程序时。ASP.NET是一个由微软开发的开源Web应用程序框架,它允许开发者使用多种编程语言(包括VB.NET)来创建Web应用程序。
42 5
|
15天前
|
安全 API 开发者
Web 开发新风尚!Python RESTful API 设计与实现,让你的接口更懂开发者心!
在当前的Web开发中,Python因能构建高效简洁的RESTful API而备受青睐,大大提升了开发效率和用户体验。本文将介绍RESTful API的基本原则及其在Python中的实现方法。以Flask为例,演示了如何通过不同的HTTP方法(如GET、POST、PUT、DELETE)来创建、读取、更新和删除用户信息。此示例还包括了基本的路由设置及操作,为开发者提供了清晰的API交互指南。
66 6
|
14天前
|
存储 JSON API
实战派教程!Python Web开发中RESTful API的设计哲学与实现技巧,一网打尽!
在数字化时代,Web API成为连接前后端及构建复杂应用的关键。RESTful API因简洁直观而广受欢迎。本文通过实战案例,介绍Python Web开发中的RESTful API设计哲学与技巧,包括使用Flask框架构建一个图书管理系统的API,涵盖资源定义、请求响应设计及实现示例。通过准确使用HTTP状态码、版本控制、错误处理及文档化等技巧,帮助你深入理解RESTful API的设计与实现。希望本文能助力你的API设计之旅。
39 3
|
15天前
|
JSON API 数据库
从零到英雄?一篇文章带你搞定Python Web开发中的RESTful API实现!
在Python的Web开发领域中,RESTful API是核心技能之一。本教程将从零开始,通过实战案例教你如何使用Flask框架搭建RESTful API。首先确保已安装Python和Flask,接着通过创建一个简单的用户管理系统,逐步实现用户信息的增删改查(CRUD)操作。我们将定义路由并处理HTTP请求,最终构建出功能完整的Web服务。无论是初学者还是有经验的开发者,都能从中受益,迈出成为Web开发高手的重要一步。
38 4
|
13天前
|
开发框架 JSON 缓存
震撼发布!Python Web开发框架下的RESTful API设计全攻略,让数据交互更自由!
在数字化浪潮推动下,RESTful API成为Web开发中不可或缺的部分。本文详细介绍了在Python环境下如何设计并实现高效、可扩展的RESTful API,涵盖框架选择、资源定义、HTTP方法应用及响应格式设计等内容,并提供了基于Flask的示例代码。此外,还讨论了版本控制、文档化、安全性和性能优化等最佳实践,帮助开发者实现更流畅的数据交互体验。
35 1
|
15天前
|
JSON API 开发者
惊!Python Web开发新纪元,RESTful API设计竟能如此性感撩人?
在这个Python Web开发的新纪元里,RESTful API的设计已经超越了简单的技术实现,成为了一种追求极致用户体验和开发者友好的艺术表达。通过优雅的URL设计、合理的HTTP状态码使用、清晰的错误处理、灵活的版本控制以及严格的安全性措施,我们能够让RESTful API变得更加“性感撩人”,为Web应用注入新的活力与魅力。
34 3
|
17天前
|
JSON API 数据格式
深度剖析!Python Web 开发中 RESTful API 的每一个细节,你不可不知的秘密!
在 Python Web 开发中,RESTful API 是构建强大应用的关键,基于 Representational State Transfer 架构风格,利用 HTTP 卞性能。通过 GET、POST、PUT 和 DELETE 方法分别实现资源的读取、创建、更新和删除操作。示例代码展示了如何使用 Flask 路由处理这些请求,并强调了状态码的正确使用,如 200 表示成功,404 表示未找到资源等。
38 5
|
2月前
|
存储 消息中间件 前端开发
Web2py框架下的神秘力量:如何轻松集成第三方API,让你的应用不再孤单!
【8月更文挑战第31天】在开发现代Web应用时,常需集成第三方服务如支付网关、数据存储等。本文将指导你使用Web2py框架无缝接入第三方API。通过实例演示从注册获取API密钥、创建控制器、发送HTTP请求到处理响应的全过程。利用`requests`库与Web2py的内置功能,轻松实现API交互。文章详细介绍了如何编写RESTful控制器,处理API请求及响应,确保数据安全传输。通过本教程,你将学会如何高效整合第三方服务,拓展应用功能。欢迎留言交流心得与建议。
37 1
下一篇
无影云桌面