1.前言
从进入公司以来，一直都是在做WebApi接口，在刚开始的时候还没有认识到API文档的重要性，仅仅是因为别人说它很重要，通过一段时间的接口开发之后，自己越发认识到一个规范的接口文档的重要性。从一开始使用Word来写API文档，但是存在更新的难题，后台转到有道云笔记，效果还是很不理想，再到后来知道VisualStudio其实是可以自动生成API文档的，而我们的项目中也有用到这种方式的变种（同事使用jQuery根据xml文档生成的），不过貌似Swagger使用的也是根据VS的xml文档来生成API文档，不过swagger的功能更加强大。
2.安装Swagger
一般来说安装程序都有两种方式，一种是在NuGet包管理器，一种是NuGet程序台命令。
* 右键点击解决方案->管理解决方案的NuGet程序包->搜索swaggerui->安装Swashbuckle
* Install-Package Swashbuckle
3.配置Swagger
配置教程来源于博客园,出处https://www.cnblogs.com/webenh/p/7513090.html
1.去除注释,获取XML文档
- 安装完成之后会在项目目录 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件，用于配置 SwaggerUI 相关展示行为。将代码里面的无用注释去除（为了简洁）。
- 在方法体内插入如下代码:
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
.EnableSwagger(c =>
{
//文档版本
c.SingleApiVersion("v1", "MyWeAPI");
//获取xml文件
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
})
- 添加如下方法：
/// <summary>
/// 获取VisualStudio产生的XML文档位置
/// </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 文档文件”，编译过程中生成类库的注释文件
2.添加HTTP Header
首先我们需要创建一个 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"
});
}
}
}
}
在配置方法类中添加注册代码:
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
//文档版本
c.SingleApiVersion("v1", "MyWeAPI");
//获取xml文件
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
//请求头配置
c.OperationFilter<HttpHeaderFilter>();
})
.EnableSwaggerUi(c =>
{
});
然后再Controller或者Action上添加过滤器:
[AccessKey]
3.上传文件参数
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"
});
}
}
}
}
添加注册配置
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
//文档版本
c.SingleApiVersion("v1", "MyWeAPI");
//获取xml文件
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
//请求头配置
c.OperationFilter<HttpHeaderFilter>();
//上传文件配置
c.OperationFilter<UploadFilter>();
})
.EnableSwaggerUi(c =>
{
});
4.收尾
至此安装就算是结束了,实际使用上还有一些问题比如说汉化问题，这些后续再搞，主要教程都是来源于网友的分享，文章中已注明出处，主要记录下来方便自己查看。
Comments | NOTHING