一、 为什么使用swagger
swagger是一种API文档管理的框架
1.可以在代码中添加注释,且自动生成API文档,无需再次编写,友好的界面让API文档更易懂。
2.一站式服务,只需要访问swagger的地址,就可以看到所有的后台接口和功能,并且能测试接口状态,真正是彻底的前后端分离了。
3.内嵌调试,可以查看接口状态和返回值结果很方便。
思考:如果能在把请求日志也集成进去就更好了。
二 、开始一步一步搭建swagger
第一步:创建一个.NET CORE的web项目(这么简单的事情,跳过,我用的API项目,我不晓得MVC项目可以不)
第二步:使用Swagger ,安装Nuget包。
第三步:接下来就是需要到 Startup.cs 类
第四步:找到ConfigureServices 注册swagger服务
代码复制:
var ApiName = "Webapi.Core";
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("V1", new OpenApiInfo
{
// {ApiName} 定义成全局变量,方便修改
Version = "V1",
Title = $"{ApiName} 接口文档——Netcore 3.0",
Description = $"{ApiName} HTTP API V1",
});
c.OrderActionsBy(o => o.RelativePath);
});
第五步:接着在StartUp类中找到Configure方法编辑,这里面RoutePrefix 就是你需要访问的url路径后面的路由比如 我们访问 localhost:8080/ApiDoc就可以跳转到Swagger的页面
代码复制:
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint($"/swagger/V1/swagger.json","WebApi.Core V1");
c.RoutePrefix = "ApiDoc";
});
第六步:把IIS 启动的注释,项目启动的Url改成根目录
这里比较离谱,我在哔哩哔哩上找到那个视频教程,都没有这一步,然后一直都是报错,最后还是一位大神帮我解决的。
第八步:接下来我们输入/ApiDoc敲回车,就可以了
三、 搭建swagger(前面搭建完成后的一下小修改)
这个也是我学完前面的那种方法再重新搭的,我要不说废话,上代码。
前面几步,引用Nuget包这些都是一样的
这里主要修改的是 注册swagger服务的代码。
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("V1", new OpenApiInfo
{
Title = "Dome.WebAPI",
Description = "宝剑锋从磨砺出,梅花香自苦寒来。",
Contact = new OpenApiContact()
{
Name = "作者:小帆",
Email = "@qq.com"
},
Version = "V1",
});
// 开启接口注释
var xmlPath = Path.Combine(AppContext.BaseDirectory, "Dome.WebApi.xml");
c.IncludeXmlComments(xmlPath, true);
});
swagger服务的代码改了,那么启用Swagger组件代码也得改一下。
其实说也没改多少,UseSwaggerUI里面的东西改了一点
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint($"/swagger/V1/swagger.json", "WebApi.Core V1");
});
然后项目启动的Url可以改成这样(改成这样的话,可以直接启动,就不什么/ApiDoc)
修改项目属性(这里不想写了,找到这个页面,然后勾选一下,会生成一个绝对路径,改成虚拟的就行了。这个页面怎么找?自己慢慢找)
最后运行就可以 !!!!