微信号:opendotnet

介绍:在这里你可以谈微软.NET;Mono的跨平台开发技术,也可以谈谈其他的跨平台技术.;;在这里可以让你的.NET项目有新的思路,不局限于微软的技术栈,横跨Windows,Linux 主流平台

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

2016-05-09 07:12 海叔

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));
  • 并在当前类中添加一个方法

    /// <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

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

c.OperationFilter<HttpHeaderFilter>();

添加Web权限过滤器

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

[AccessKey]

最终显示效果

4.显示上传文件参数

SwaggerUI 有上传文件的功能和添加自定义HTTP Header 做法类似,只是我们通过特殊的设置来标示API具有上传文件的功能

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

c.OperationFilter<UploadFilter>();

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/


相关文章:


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


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

 
dotNET跨平台 更多文章 .NET 基金会及 Roslyn 编译器 ASP.NET 5开源及 .NET Core Framework 如何迎接新的 .NET 时代 迎接 Entity Framework 7 皮裤原理和运营微信公众号dotNET跨平台
猜您喜欢 Android编译及Dex过程源码分析 第一部分::任务2:第一个web应用 Android开发人员不得不收集的代码 学会JS的this这一篇就够了,根本不用记 支撑起整个互联网时代的7款开源软件