.net core2.2中使用swagger生成webapi接口文档

前端技术不断的发展,如:webpack,vue,前端路由等出现,使得前后端分离在项目中越来越普遍,后端工程师只需要完成接口以及接口文档,而今天要介绍的swagger就很好的解决了接口文档的生成问题。首先看一张完成后的截图,然后一步步图解说明如何做,当然我也提供了全部的源码,见最后的github地址。


第一步:创建一个.Net core的API项目






第二步:配置项目
安装两个nuget包,Microsoft.Extensions.PlatformAbstractions并不是Swagger所必须的,而是为了获取目录文件所需,具体看我放在github上的源码
Swashbuckle.AspNetCore
Microsoft.Extensions.PlatformAbstractions


编译时生成注释文档,前面第一种Swagger截图上每个接口的注释内容就来之这个生成的文档


启动的首页设置,你也可以不用设置,每次手动输入地址,类似这样:192.168.1.168/swagger


第三步:添加核心代码
添加swagger文档生成服务
c.IncludeXmlComments(XmlCommentsFilePath),使用这个就是为了显示接口的注释,接口是提供给app,小程序等客户端使用,有注释更加友好
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
c.IncludeXmlComments(XmlCommentsFilePath);
});
}

获取接口注释文档
static string XmlCommentsFilePath
{
get
{
var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var fileName = typeof(Startup).GetTypeInfo().Assembly.GetName().Name + ".xml";
return Path.Combine(basePath, fileName);
}
}

添加最后的两个中间件配置,其余的代码Startup.cs自带
ModelRendering.Example意思Swagger UI页面的接口是显示Example,您也可以设置Model,如代码后面的图片
DocExpansion.None,意思把接口文档收起来,还有List,Full两个选项,看个人喜好,如果接口多收起来更好,如果少可以用List,或者Full
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();
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
c.DefaultModelRendering(ModelRendering.Example);
c.DocExpansion(DocExpansion.None);
});
}



添加一个控制器,加两个方法,注意!!必须得有属性路由,也就是跟在HttpGet/HttpPost后面的地址
[Produces("application/json")]意思相应内容的类型,如代码后的截图
/// <summary>
/// 程序员网址导航
/// </summary>
[Route("hrefs")]
[Produces("application/json")]
[ApiController]
public class HrefsController : ControllerBase
{
/// <summary>
/// 获取最近文章
/// </summary>
/// <param name="top"></param>
/// <returns></returns>
[HttpGet("list/{top}")]
public IEnumerable<Article> GetArticleList(int top)
{
List<Article> list = new List<Article>();
Article article = new Article();
article.Body = "Hello World!";
article.Id = 10;
article.Title = "I am ok!";

list.Add(article);
return list;
}

/// <summary>
/// 保存文章
/// </summary>
/// <param name="article"></param>
/// <returns></returns>
[HttpPost("save")]
public ActionResult<int> Save(Article article)
{
var result = 0;
return result;
}
}



第四步:启动
https://localhost:44308/swagger
它将自动跳转到
https://localhost:44308/swagger/index.html
这时你就又看见开头的截图了,重温一次


总结:使用Visual Studio 2019,.Net Core 2.2,Swagger 4.0.1,稍低一点的版本使用方式是一样的,比如.Net Core 2.1,全部的代码已经托管到github。

github源码:https://github.com/iissy/swaggernetcore
Posted by 何敏 on 2019/06/01 16:51:31