上一步我们创建好CoreApi
接下来在框架中加入 Swagger 并发布 到 IIS
(1)首先点击依赖项》管理Nuget包
(2)输入 Swashbuckle.aspnetCore 比如:
图中两个Swagger 插件需要我们安装 注意:我这里已经安装过显示的是 卸载
(3) 在框架中 添加Swagger 注解的帮助类 HttpHeaderOperation 下面是我完整的.CS文件
usingSystem;usingSystem.Collections.Generic;usingSystem.Linq;usingSystem.Threading.Tasks;//添加引用
usingSwashbuckle.AspNetCore.Swagger;usingSwashbuckle.AspNetCore.SwaggerGen;usingMicrosoft.AspNetCore.Authorization;namespaceWebCoreApi
{public classHttpHeaderOperation : IOperationFilter
{///
///实现接口///
///
///
public voidApply(Operation operation, OperationFilterContext context)
{if (operation.Parameters == null)
{
operation.Parameters= new List();
}var actionAttrs =context.ApiDescription.ActionAttributes();var isAuthorized = actionAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));if (isAuthorized == false) //提供action都没有权限特性标记,检查控制器有没有
{var controllerAttrs =context.ApiDescription.ControllerAttributes();
isAuthorized= controllerAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));
}var isAllowAnonymous = actionAttrs.Any(a => a.GetType() == typeof(AllowAnonymousAttribute));if (isAuthorized && isAllowAnonymous == false)
{
operation.Parameters.Add(newNonBodyParameter()
{
Name= "Authorization", //添加Authorization头部参数
In = "header",
Type= "string",
Required= false});
}
}
}
}
View Code
(4) 添加 Swagger 的·服务方法 在 Startup中的 ConfigureServices方法里
public voidConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(x=>{
x.SwaggerDoc("v1", newInfo
{
Version= "v1", //版本号
Title = "Szl接口文档", //标题
Description = "RESTful API",
TermsOfService= "",//服务的条件//第一个参数Name 创建人名称/也可以是 负责人名称 第二个参数 联系邮箱
Contact = new Contact { Name = "Su", Email = "szl_0000@126.com", Url = "北京"}
});//获取设置配置信息的 的路径对象 swagger界面配置
var basePath =PlatformServices.Default.Application.ApplicationBasePath;var xmlPath = Path.Combine(basePath, "AspNetCoreApiSwagger.xml");
x.IncludeXmlComments(xmlPath);
x.OperationFilter(); //添加httpHeader参数
});
}
View Code
(5)添加 Swagger 启动项 在 Startup中的 Configure方法里
public voidConfigure(IApplicationBuilder app, IHostingEnvironment env)
{if(env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseMvc();
app.UseSwagger();//指定站点
app.UseSwaggerUI(x =>{//做出一个限制信息 描述
x.SwaggerEndpoint("/swagger/v1/swagger.json", "TwBusManagement API V1");//显示在发出请求时发送的标题
x.ShowRequestHeaders();
});
}
View Code
(6) 在框架自动生成的 Api 控制器里Post的方法上加入 注解(其他方法也可以,我只是举例)
///
///AspNet Core Post请求///
/// User类
///
///访问参数///POST///{///"value": "0e7ad584-7788-4ab1-95a6-ca0a5b444cbb",///}///
///
/// 返回新创建项
/// 如果为空时
[HttpPost]
[ProducesResponseType(typeof(User), 201)]
[ProducesResponseType(typeof(User), 400)]public voidPost([FromBody]User value)
{
}
View Code
注解的含义如下
summary 用来描述 方法的作用
remarks 用来描述传入的参数格式/也可以把调用的值放入里面
response 定义两个返回状态
User 类
///
///用户类///
public classUser
{///
///用户ID///
public int UserID { get; set; }///
///用户名称///
public int UserName { get; set; }///
///用户年龄///
public int UserAge { get; set; }
}
View Code
(7)在框架中 添加 AspNetCoreApiSwagger.xml 文件 一定要注意的是 xml 文件必须定义一个根节点 不然会报错 ,XML的属性 改为 始终复制 (XML文件在 第四步骤中有用到)
(8)设置 项目的生成 输出路径
(9) 发布 以文件夹发布就行
(10)部署IIS 说一下注意点 改成无托管代码
(11)打开IIS服务 中的模块
(12)查看是否有 AspNetCoreModule 没有进行安装 我是在国外的网站下载的
(13) 如果在运行部署的API 发生了错误
我们在 Program 中加入 如代码所示 可以帮助我们准确定义的问题所在
public classProgram
{public static void Main(string[] args)
{
BuildWebHost(args).Run();
}public static IWebHost BuildWebHost(string[] args) =>WebHost.CreateDefaultBuilder(args)//发布程序出现错误帮助定位详细错误信息//.UseKestrel()//.UseContentRoot(Directory.GetCurrentDirectory())//.UseSetting("detailedErrors", "true")//.UseIISIntegration()
.CaptureStartupErrors(true)
.UseStartup()
.Build();
}
View Code
OK 今天就完成了,
以后会描述一下 框架的基础知识 比如 应用程序的启动、日子、路由、静态文件、WebSockteS 等,
等到基础描述过后,在框架中加入一些我闷在实战中用到的,希望大家多多指出错误不足之处,这是我的学习。
补充一下显示结果,开始的时候忘记截图了
有人在实践中遇到了没有注释的问题
在启动的时候
注意这里 XML名称是否错误
代码中读取的注释信息在 AspNetCoreApiSwagger.xml中,项目启动后会把注释信息生成到AspNetCoreApiSwagger.xml中