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

1.前言

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));

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

  /// /// 

/// /// protected static string GetXmlCommentsPath(string name){ return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name); }

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

• 添加百度音乐 3个API

• 访问 http:///swagger/ui/index,最终显示效果

• 咱们经过API 测试API 是否成功运行

3.添加自定义HTTP Header

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

首先咱们须要建立一个 IOperationFilter 接口的类。IOperationFilter

在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码

c.OperationFilter();

添加Web权限过滤器

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

[AccessKey]

最终显示效果

4.显示上传文件参数

SwaggerUI 有上传文件的功能和添加自定义HTTP Header 作法相似，只是咱们经过特殊的设置来标示API具备上传文件的功能

在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码

c.OperationFilter();

API 文档展现效果

5.版本和资源

你能够经过下列链接获取相关说明。
OnlineAPI Demo 项目下载
OnlineAPI Demo下载
Swashbuckle 项目地址：
https://github.com/domaindrivendev/Swashbuckle
swagger-ui 项目地址：
https://github.com/swagger-api/swagger-ui
swagger-ui 官网地址：
http://swagger.io/swagger-ui/

 

相关文章：

• WebAPI前置知识:HTTP与RestfulAPI

• WEB API系列（一）：WEB API的适用场景、第一个实例

• WEB API 系列（二） Filter的使用以及执行顺序

• ASP.NET Web API 安全筛选器

• Web API 基于ASP.NET Identity的Basic Authentication

• ASP.NET Web Api使用CacheCow和ETag缓存资源

• 使用 West Wind WebSurge 对 ASP.NET Web API 服务进行压力测试

• Web API应用支持HTTPS的经验总结

• Dion Hinchcliffe谈Web API的过去与将来

• WebAPI生成可导入到PostMan的数据

 

原文地址：http://www.cnblogs.com/Arrays/p/5146194.html

---

.NET社区新闻，深度好文，微信中搜索dotNET跨平台或扫描二维码关注