Swagger 的使用

背景: mvc api 下使用swagger

.net core 和.net framework 会有一些区别

一、core 里面直接nuget 搜索 Swashbuckle.AspNetCore 安装
1、在startup 类中添加swagger 配置信息
public void ConfigureServices(IServiceCollection services)
{
// 注册Swagger服务
services.AddSwaggerGen(c =>
{
// 添加文档信息
c.SwaggerDoc("v1", new Info { Title = "CoreWebApi", Version = "v1" });
});
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}
2、在 Startup类Configure 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}

app.UseHttpsRedirection();
// 启用Swagger中间件
app.UseSwagger();

// 配置SwaggerUI
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "CoreWebApi");

});
app.UseMvc();
}
配置 输出xml文档文件

二、mvc中 下载并添加WebActivatorEx 和 Swashbuckle.Core 两个dll
如果vs版本足够，可以直接使用nuget 下载，目前我这边使用vs2010 没法直接添加这两个dll。所以在App_Start 下手动添加了SwaggerConfig.cs 文件，配置 输出xml文档文件

原则上来说，有了上述两种配置，可以出现swagger的界面

部分注释项
[ApiExplorerSettings(IgnoreApi = true)]
可以隐藏controller 以及 action

输出实体 字段显示，两种方式
1、(api返回的时候，使用统一的泛型) 例：
public class BaseResponseEmployee<T>
{
public BaseResponseEmployee()
{
errorcode = 0;
errormsg = "";
}
public int errorcode { get; set; }
public string errormsg { get; set; }
public T data { get; set; }
}
2、[SwaggerResponse(HttpStatusCode.OK,Description= "文档注释", Type=typeof(EmployeeAnnouncement))]

swagger 设置header 传值

class AddRequiredAuthorizationHeaderParameter : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
if (operation.parameters == null)
operation.parameters = new List<Parameter>();
//operation.parameters.Add(new Parameter
//{
// name = "version",
// @in = "header",
// type = "string",
// required = true,
// description = "version"
//});

operation.parameters.Add(new Parameter
{
name = "lang",
@in = "header",
type = "string",
required = false,
description = "language, eg: zh-cn"
});
operation.parameters.Add(new Parameter
{
name = "token",
@in = "header",
type = "string",
required = false,
description = "token"
});

}
}

 另外使用安装swagger 使用时发现swagger 内置了Newtonsonft.Json  10.0 的版本  和现有系统冲突 

需要在webconfig使用配置指定代码

<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<dependentAssembly>
<assemblyIdentity name="Newtonsoft.Json" culture="neutral" publicKeyToken="30ad4fe6b2a6aeed" />
<bindingRedirect oldVersion="0.0.0.0-10.0.0.0" newVersion="6.0.0.0" />
</dependentAssembly>
</assemblyBinding>
</runtime>