如何使 WebAPI 自动生成漂亮又实用在线API文档
发布网友
发布时间：2022-03-31 18:54
共6个回答
懂视网
时间：2022-03-31 23:16
Web API是网络应用程序接口。包含了广泛的功能，网络应用通过API接口，可以实现存储服务、消息服务、计算服务等能力，利用这些能力可以进行开发出强大功能的web应用。
web平台归为6个基本设施，并简要概述些相关产品。其间的线索是这些产品都提供了API，这意味者他们本身可以被其他服务整合。存储服务：存储服务关注抽象化和虚拟化存储。这个领域的领头羊是amazon s3，在我的article in web 2.0 journal中对其曾有较深入的探讨。消息服务：消息服务在概念上类似于传统意义上的中间件。由于技术和商业上的复杂性，它们还没有被大规模开发。计算服务：目前还没有一个一般的可以通过api访问的web计算服务黑盒，但有不少技术指向这个方向。信息服务：信息服务提供海量特定的信息。包括像Google Maps API的地理数据，像Amazon E-Commerce，Amazon historcal Pricing Services的产品数据。搜索服务：因为搜索在web领域的基础和统治地位，搜索服务构成了新的web基础架构的关键部分。Google searchapi是较早的如今已成典型的搜索抽象机制。
热心网友
时间：2022-03-31 20:24
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 == "1234567";
}
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 文档展示效果
热心网友
时间：2022-03-31 21:42
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")
热心网友
时间：2022-03-31 23:16
Baklib首页
Baklib作为一款支持私有化部署的SaaS云产品，具有易构建、知识迁移与备份简单、使用上手容易及移动端体验较好等优点。
Baklib支持API接口
提供大量的API接口文档教程，帮助开发者更好进行开发工作。
BaklibAPI教程文档展示
Baklib在线轻松编辑
支持结构化解构以实现人工智能语义识别，支持多终端自适应预览的流畅体验。除了常见视频、图片、代码块....添加外还可以对选中的文字进行样式添加加粗、高亮、链接，还支持Markdown在线编辑器。
Baklib编辑界面
简介优雅的排版
简洁高效的页面一定是产品发行说明文档的首选，在发行说明展示界面上，我们设置了舒服的文字排版，标题多级展示做到用户可以通过下拉列表就可轻松找到自己关系的问题。
Baklib界面展示
个性网站设置
Baklib允许了用户对展示网站进行了高自由度的设置，用户可以给展示出来的站点进行域名设置、站点的名称、站点图标、站点标语、站点模板、站点样色等进行设置。并且对于网站的权限可以分为私密、公开和密码访问，可以对指定人群开放，并且可以设置的网站域名，建设属于你自己的个性网站。
网站安全
Baklib采用先进而灵活的云服务构架，Saas化服务，从内部编辑到外部分享保障用户的数据安全和。
Baklib数据安全界面
热心网友
时间：2022-04-01 01:08
weidApi 百度一下，你懂的
热心网友
时间：2022-04-01 03:16
很多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
