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中不会用到的一些文件,使其看上去比较简洁。

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 文档展示效果

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 自动生成漂亮又实用在线API文档的更多相关文章

  1. WebApi生成在线API文档--Swagger

    1.前言 1.1 SwaggerUI SwaggerUI 是一个简单的Restful API 测试和文档工具.简单.漂亮.易用(官方demo).通过读取JSON 配置显示API. 项目本身仅仅也只依赖 ...

  2. 第十二节:WebApi自动生成在线Api文档的两种方式

    一. WebApi自带生成api文档 1. 说明 通过观察,发现WebApi项目中Area文件夹下有一个HelpPage文件夹,如下图,该文件夹就是WebApi自带的生成Api的方式,如果该文件夹没了 ...

  3. 使用swagger实现在线api文档自动生成 在线测试api接口

    使用vs nuget包管理工具搜索Swashbuckle 然后安装便可 注释依赖于vs生成的xml注释文件

  4. 重新生成RF的测试库API文档

    在dos窗口下执行如下命令: 命令:python -m robot.libdoc 库名称  生成的API文件名.html 例如:python -m robot.libdoc MongoDBLibrar ...

  5. C#WebApi 接口增加备注和测试 默认api文档

    1:配置 接口注释. (1)配置生成xml的路径.我们在项目上面点右键→属性→生成标签页配置xml的路径. (2)在xml的读取路径:在Areas\HelpPage\App_Start\HelpPag ...

  6. 【WebAPI No.4】Swagger实现API文档功能

    介绍: Swagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案.简单的说就是一款让你更好的书写API文档的框架. 我们为 ...

  7. 【转载】Java Restful API 文档生成工具 smart-doc

    谁说生成api文档就必须要定义注解? 谁说生成接口请求和返回示例必须要在线? 用代码去探路,不断尝试更多文档交付的可能性. 如果代码有生命,为什么不换种方式和它对话! 一.背景 没有背景.就自己做自己 ...

  8. 干掉 Postman?测试接口直接生成API文档,这个工具贼好用

    大家好,我是小富~ 前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下. ShowDoc一个非常适合团队的在线API文档工具,也支持用docke ...

  9. 浅析如何在Nancy中生成API文档

    前言 前后端分离,或许是现如今最为流行开发方式,包括UWP.Android和IOS这样的手机客户端都是需要调用后台的API来进行数据的交互. 但是这样对前端开发和APP开发就会面临这样一个问题:如何知 ...

随机推荐

  1. Senparc.Weixin.MP SDK 微信公众平台开发教程(十七):个性化菜单接口说明

    前不久微信上线了个性化菜单接口,Senparc.Weixin SDK也已经同步更新. 本次更新升级Senparc.Weixin.MP版本到v13.5.2,依赖Senparc.Weixin版本4.5.4 ...

  2. java.io.IOException: invalid header field

    通过本文, 我们明白了什么是 jar的清单文件 MANIFEST.MF, 简单示例: E:\ws\Test\WEB-INF\classes>jar cvfm testCL.jar ListTes ...

  3. Linux内核目录结构

    arch 包括所有和体系结构相关的核心代码. include 包括编译内核所需要的大部分头文件 init 包含内核的初始化代码(不是系统的引导代码),有main.c和Version.c两个文件 mm ...

  4. jQuery通过parent()和parents()方法访问父级元素

    <div class="inputGroup"> <p>2.您的最高学历是?</p> <label><input type=& ...

  5. WaitType:ASYNC_IO_COMPLETION

    项目组有一个数据库备份的Job运行异常,该Job将备份数据存储到remote server上,平时5个小时就能完成的备份操作,现在运行19个小时还没有完成,backup命令的Wait type是 AS ...

  6. 专业上的常用的工具和类库集 By 老衣

    Visual Studio 2013 扩展 CodeMaid: 可快速整理代码文件,清理不必要的代码和杂乱的格式.并在开发时实时提供代码复杂度的报告,以便帮助开发人员降低代码复杂度.提高代码质量. C ...

  7. SQL Server游标

    什么是游标 结果集,结果集就是select查询之后返回的所有行数据的集合. 游标则是处理结果集的一种机制吧,它可以定位到结果集中的某一行,多数据进行读写,也可以移动游标定位到你所需要的行中进行操作数据 ...

  8. 那些让IE6-8羞愧的替补型js

    1,html5shiv 这个js特别简单,可以让IE8识别一些新的标签,常用的比如 header footor section,就能使用更好的语义的标签了. 引入方式: <!--[if lt I ...

  9. 【转】oracle中in和exists的区别

    原文地址:http://blog.itpub.net/7478833/viewspace-441043/ 感谢作者   in 和 exists区别   in 是把外表和内表作hash join,而ex ...

  10. Struts.xml中Action的method与路径的三种匹配方法

    原文  http://blog.csdn.net/woshixuye/article/details/7734482 首先我们有一个Action——UserAction public class Us ...