Swagger使用教程 SwashbuckleEx

自从之前写了一篇《Webapi文档描述-swagger优化》这篇文章后，欠了大家一篇使用文档的说明，现在给大家补上哈。

二、环境

.Net Framework 4.5

WebApi 2

SwashbuckleEx 1.1.2：个人修改后的版本

三、SwashbuclkeEx 优化说明

汉化：支持中、英文。

接口搜索：模块名、注释名、接口名

注释：控制器备注、开发进度说明、开发人员注释

区域文档分组：支持多种文档切换、并分组显示在左侧，可通过点击进行切换文档

接口数量统计

展示如下：

三、SwashbuckleEx 使用文档 4.1 安装SwashbuckleEx Install-Package SwashbuckleEx 4.2 包含指定XML注释文件

设置库生成Xml文件：右键点击项目属性->生成->输出 勾选Xml文档文件

配置注释文件：IncludeXmlComments('绝对路径')，可配置多个，但是发布服务器的时候需要将XML带上，如果没有则会访问报错。

GlobalConfiguration.Configuration .EnableSwagger(c => { c.IncludeXmlComments(string.Format("{0}/bin/SwashbuckleEx.WebApiTest.XML", AppDomain.CurrentDomain.BaseDirectory)); }

4.3 简单Api文档信息配置-单文档

配置Api版本信息：SingleApiVersion('版本','文档标题')

配置联系方式：Contarct

邮箱：Email

创建人：Name

联系地址：Url

配置许可证：Lincese

许可证名称：Name

地址：Url

配置备注：Description('自定义内容')

配置服务条款：TermsOfService('条款内容')。这个方法没看到在界面哪个地方展示。

配置代码如下：

GlobalConfiguration.Configuration .EnableSwagger(c => { c.SingleApiVersion("v1", "Test.WebApi").Contact(x => { x.Email("jianxuanhuo1@126.com"); x.Name("jian玄冰"); x.Url("https://www.cnblogs.com/jianxuanbing"); }).TermsOfService("jian玄冰").License(x => { x.Name("MIT"); x.Url("https://www.cnblogs.com/jianxuanbing"); }).Description("自定义文案内容，可以随便输入内容"); }

效果图如下：

4.4 多版本Api文档信息配置-多文档

该方式主要用于API版本处理使用，但是本人用区域进行划分，用于分隔多个系统的接口。

路由配置：WebApiConfig.cs

public static class WebApiConfig { public static void Register(HttpConfiguration config) { // Web API 路由 config.MapHttpAttributeRoutes(); config.Routes.MapHttpRoute( name: "AdminApi", routeTemplate: "api/Admin/{controller}/{action}/{id}", defaults: new { action = RouteParameter.Optional, id = RouteParameter.Optional, namespaces = new string[] { "SwashbuckleEx.WebApiTest.Areas.Admin.Controllers" } }); config.Routes.MapHttpRoute( name: "ClientApi", routeTemplate: "api/Client/{controller}/{action}/{id}", defaults: new { action = RouteParameter.Optional, id = RouteParameter.Optional, namespaces = new string[] { "SwashbuckleEx.WebApiTest.Areas.Client.Controllers" } }); config.Routes.MapHttpRoute( name: "CommonApi", routeTemplate: "api/{controller}/{action}/{id}", defaults: new { action = RouteParameter.Optional, id = RouteParameter.Optional, namespaces = new string[] { "SwashbuckleEx.WebApiTest.Controllers" } } ); } }

配置Api版本信息：MultipleApiVersions()
Version进行了修改，提供支持默认路由
```
public static void Register()
{
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.MultipleApiVersions(ResolveAreasSupportByRouteConstraint, (vc) =>
{
vc.Version("Admin", "中文后台 API").Description("这个用于测试一下备注信息").TermsOfService("jian玄冰").License(
x =>
{
x.Name("jian玄冰");
x.Url("https://www.cnblogs.com/jianxuanbing");
})
.Contact(x =>
{
x.Name("2017").Email("jianxuanhuo1@126.com").Url("www.baidu.xxxx");
});
vc.Version("v1", "Common API", true);// 设置为默认路由

vc.Version("Client", "Client API"); }); // 添加区域路由文档过滤 c.DocumentFilter<AddAreasSupportDocumentFilter>(); }

}