003 在.Net Core 中使用 Swagger
2021-03-13 17:33
阅读：623
003 在.Net Core 中使用 Swagger
ASP.NET CoreWeb ApiSwagger
引出问题
有的时候我们编写了一个API项目,但是没有太多时间来编写接口文档,这个时候会增加与消费者(API)调用者的沟通成本,这个时候Swagger的使用就很有必要了.
在Asp .Net Core Web API 中使用Swagger
-
在WebApi,所在的项目中,通过Nuget安装
SwashBuckle.AspNetCore包,此包依赖如下包:- SwashBuckle.AspNetCore.Swagger
- SwashBuckle.AspNetCore.SwaggerGen
- SwashBuckle.AspNetCore.SwaggerUI
- SwashBuckle.AspNetCore.ApiDescription.Server
-
在
Startup.cs类的ConfigureServices方法中配置如下注入:
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo { Title = "WebAPI项目的含义名称", Version = "v1" });
//添加中文注释
var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
var commentsFileName = typeof(Program).Assembly.GetName().Name + ".XML";
var xmlPath = Path.Combine(basePath, commentsFileName);
options.IncludeXmlComments(xmlPath);
//添加Model类的注释
var modelFileName = "Leisure.BabakuaiBus.DtoModels.xml";
var modelXmlPath = Path.Combine(basePath, modelFileName);
options.IncludeXmlComments(modelXmlPath);
options.DocInclusionPredicate((docName, description) => true);
});3.在Startup.cs类的Configure方法中,启用如下中间件:
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "CIT WebAPI v1");
});到此在项目中应用Swagger的过程基本完成,是不是很简单,下面启动服务看效果:
Swagger页面
在接口中显示文档描述
有的时候我们需要再Swagger文档中显示接口描述,那么我们应该怎么做呢?
- 我们在项目中首相需要给接口,以及实体类加上C#文档注释(必须要现有文档注释).
- 生成操作如下:
- 我们在WebApi所在的项目中,在其属性中的生成页面中,勾选上XML文档即可.
Swagger可以显示的接口文档
此处需要 注意 一点,如果我们也想让输入输出参数的文档注释也显示再Swagger中那么我们也需要将输入输出参数实体类所在的项目,也需要生成XML文档文件,并且我们需要将生成好的文档文件放到Asp .Net Core运行所在的目录中.
在Swagger文档中过滤接口
有的时候有的接口我们并不想将整个项目下的所有API接口都显示再Swagger文档中,暴露给消费者,那么我们应该怎么做呢?
很简单,我们只需要再不想暴露出来的Action上加上特性[ApiExplorerSettings(IgnoreApi = true)]即可.
示例代码:
[HttpGet]
[ApiExplorerSettings(IgnoreApi = true)]
public ActionResult Index(string appKey , string userName ,string userPwd)
{
//todo
}
参考文章地址: 在.NetCore WebApi中过滤Swagger文档显示接口方法
使用Swagger的其它注意事项:
方法名相同的报错
上一篇：每天认识几个HTTP 响应码
下一篇：计算5的n次幂html代码
文章来自：搜素材网的编程语言模块，转载请注明文章出处。
文章标题：003 在.Net Core 中使用 Swagger
文章链接：http://soscw.com/index.php/essay/64208.html
文章标题：003 在.Net Core 中使用 Swagger
文章链接：http://soscw.com/index.php/essay/64208.html
评论
亲，登录后才可以留言！