如何使 WebAPI 自动生成漂亮又实用在线API文档

Posted 2023-03-01

1.1 SwaggerUI

SwaggerUI 是一个简单的Restful API 测试和文档工具。简单、漂亮、易用（官方demo）。通过读取JSON 配置显示API. 项目本身仅仅也只依赖一些 html,css.js静态文件. 你可以几乎放在任何Web容器上使用。

1.2 Swashbuckle

Swashbuckle 是.NET类库,可以将WebAPI所有开放的控制器方法生成对应SwaggerUI的JSON配置。再通过SwaggerUI 显示出来。类库中已经包含SwaggerUI 。所以不需要额外安装。

2.快速开始

创建项目 OnlineAPI来封装百度音乐服务(示例下载) ，通过API可以搜索、获取音乐的信息和播放连接。

我尽量删除一些我们demo中不会用到的一些文件，使其看上去比较简洁。

WebAPI 安装 Swashbuckle

Install-Package Swashbuckle

代码注释生成文档说明。
Swashbuckle 是通过生成的XML文件来读取注释的，生成 SwaggerUI，JSON 配置中的说明的。
安装时会在项目目录 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件，用于配置 SwaggerUI 相关展示行为的。如图：

将配置文件大概99行注释去掉并修改为
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));

并在当前类中添加一个方法

/// <summary>
/// </summary>
/// <param name="name"></param>
/// <returns></returns>
protected static string GetXmlCommentsPath(string name)

return string.Format(@"0\\bin\\1.XML", AppDomain.CurrentDomain.BaseDirectory, name);


紧接着你在此Web项目属性生成选卡中勾选 “XML 文档文件”，编译过程中生成类库的注释文件

添加百度音乐 3个API

访问 http://<youhost>/swagger/ui/index,最终显示效果

我们通过API 测试API 是否成功运行

3.添加自定义HTTP Header

在开发移动端 API时常常需要验证权限，验证参数放在Http请求头中是再好不过了。WebAPI配合过滤器验证权限即可

首先我们需要创建一个 IOperationFilter 接口的类。IOperationFilter
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Http.Description;
using System.Web.Http.Filters;
using Swashbuckle.Swagger;

namespace OnlineAPI.Utility

public class HttpHeaderFilter : IOperationFilter

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

if (operation.parameters == null) operation.parameters = new
List<Parameter>();
var filterPipeline =
apiDescription.ActionDescriptor.GetFilterPipeline();
//判断是否添加权限过滤器
var isAuthorized = filterPipeline.Select(filterInfo =>
filterInfo.Instance).Any(filter => filter is IAuthorizationFilter);
//判断是否允许匿名方法
var allowAnonymous =
apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any();

if (isAuthorized && !allowAnonymous)

operation.parameters.Add(new Parameter

name = "access-key",
@in = "header",
description = "用户访问Key",
required = false,
type = "string"
);





在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<HttpHeaderFilter>();

添加Web权限过滤器
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Web;
using System.Web.Http;
using System.Web.Http.Controllers;
using Newtonsoft.Json;

namespace OnlineAPI.Utility

/// <summary>
///
/// </summary>
public class AccessKeyAttribute : AuthorizeAttribute

/// <summary>
/// 权限验证
/// </summary>
/// <param name="actionContext"></param>
/// <returns></returns>
protected override bool IsAuthorized(HttpActionContext actionContext)

var request = actionContext.Request;
if (request.Headers.Contains("access-key"))

var accessKey = request.Headers.GetValues("access-key").SingleOrDefault();
//TODO 验证Key
return accessKey == "123456789";

return false;


/// <summary>
/// 处理未授权的请求
/// </summary>
/// <param name="actionContext"></param>
protected override void HandleUnauthorizedRequest(HttpActionContext actionContext)

var content = JsonConvert.SerializeObject(new State = HttpStatusCode.Unauthorized);
actionContext.Response = new HttpResponseMessage

Content = new StringContent(content, Encoding.UTF8, "application/json"),
StatusCode = HttpStatusCode.Unauthorized
;




在你想要的ApiController 或者是 Action 添加过滤器
[AccessKey]

最终显示效果

4.显示上传文件参数

SwaggerUI 有上传文件的功能和添加自定义HTTP Header 做法类似，只是我们通过特殊的设置来标示API具有上传文件的功能
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http.Description;
using Swashbuckle.Swagger;

namespace OnlineAPI.Utility

/// <summary>
///
/// </summary>
public class UploadFilter : IOperationFilter


/// <summary>
/// 文件上传
/// </summary>
/// <param name="operation"></param>
/// <param name="schemaRegistry"></param>
/// <param name="apiDescription"></param>
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)

if (!string.IsNullOrWhiteSpace(operation.summary) && operation.summary.Contains("upload"))

operation.consumes.Add("application/form-data");
operation.parameters.Add(new Parameter

name = "file",
@in = "formData",
required = true,
type = "file"
);





在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<UploadFilter>();

API 文档展示效果 参考技术A 1、如何引入组件
首先，我们需要定义一个API项目
然后通过Nuget引入组件。记住选下图中的第三个。

引入成功后，将向项目里面添加一些主要文件：
•Scripts\WebApiTestClient.js
•Areas\HelpPage\TestClient.css
•Areas\HelpPage\Views\Help\DisplayTemplates\TestClientDialogs.cshtml
•Areas\HelpPage\Views\Help\DisplayTemplates\TestClientReferences.cshtml
2、如何使用组件
1、修改Api.cshtml文件
通过上述步骤，就能将组件WebAPITestClient引入进来。下面我们只需要做一件事：打开文件 (根据 Areas\HelpPage\Views\Help) Api.cshtml 并添加以下内容:
•@Html.DisplayForModel("TestClientDialogs")
•@Html.DisplayForModel("TestClientReferences") 参考技术B

Baklib首页

Baklib作为一款支持私有化部署的SaaS云产品，具有易构建、知识迁移与备份简单、使用上手容易及移动端体验较好等优点。

Baklib支持API接口

提供大量的API接口文档教程，帮助开发者更好进行开发工作。

BaklibAPI教程文档展示

Baklib在线轻松编辑

支持结构化解构以实现人工智能语义识别，支持多终端自适应预览的流畅体验。除了常见视频、图片、代码块....添加外还可以对选中的文字进行样式添加加粗、高亮、链接，还支持Markdown在线编辑器。

Baklib编辑界面

简介优雅的排版

简洁高效的页面一定是产品发行说明文档的首选，在发行说明展示界面上，我们设置了舒服的文字排版，标题多级展示做到用户可以通过下拉列表就可轻松找到自己关系的问题。

Baklib界面展示

个性网站设置

Baklib允许了用户对展示网站进行了高自由度的设置，用户可以给展示出来的站点进行域名设置、站点的名称、站点图标、站点标语、站点模板、站点样色等进行设置。并且对于网站的权限可以分为私密、公开和密码访问，可以对指定人群开放，并且可以设置独立的网站域名，建设属于你自己的个性网站。

网站安全

Baklib采用先进而灵活的云服务构架，Saas化服务，从内部编辑到外部分享保障用户的数据安全和独立。

Baklib数据安全界面

参考技术C weidApi 百度一下，你懂的 参考技术D 很多API doc生成工具生成doc需要重度依赖代码里加注解的方式，并且不支持自动化测试RESTful API。

之前习惯用一款名字为 WisdomTool REST Client，它能够基于测试过的历史记录自动生成精美的RESTful API文档，完全不用在代码里加注解，支持自动化测试RESTful API，输出精美的测试报告。
轻量级的工具，功能却很精悍哦！

https://github.com/wisdomtool/rest-client

Most of API doc tools do not support automated testing.

Once used a tool called WisdomTool REST Client supports automatically generating exquisite RESTful API documentation based on history testing cases without adding annotations to the code, it also supports automated testing, and outputs exquisite report.

Lightweight tool with very powerful features!

https://github.com/wisdomtool/rest-client