ICode9

精准搜索请尝试: 精确搜索
首页 > 其他分享> 文章详细

003 在.Net Core 中使用 Swagger

2020-05-02 14:01:07  阅读:418  来源: 互联网

标签:Core AspNetCore 接口 003 文档 var Net Swagger options


003 在.Net Core 中使用 Swagger

ASP.NET CoreWeb ApiSwagger

引出问题

有的时候我们编写了一个API项目,但是没有太多时间来编写接口文档,这个时候会增加与消费者(API)调用者的沟通成本,这个时候Swagger的使用就很有必要了.

在Asp .Net Core Web API 中使用Swagger

  1. 在WebApi,所在的项目中,通过Nuget安装SwashBuckle.AspNetCore包,此包依赖如下包:

    • SwashBuckle.AspNetCore.Swagger
    • SwashBuckle.AspNetCore.SwaggerGen
    • SwashBuckle.AspNetCore.SwaggerUI
    • SwashBuckle.AspNetCore.ApiDescription.Server
  2. 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页面

在接口中显示文档描述

有的时候我们需要再Swagger文档中显示接口描述,那么我们应该怎么做呢?

  1. 我们在项目中首相需要给接口,以及实体类加上C#文档注释(必须要现有文档注释).
  2. 生成操作如下:
    • 我们在WebApi所在的项目中,在其属性中的生成页面中,勾选上XML文档即可.

Swagger可以显示的接口文档
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的其它注意事项:

方法名相同的报错
方法名相同的报错

标签:Core,AspNetCore,接口,003,文档,var,Net,Swagger,options
来源: https://www.cnblogs.com/HelloZyjS/p/12817906.html

本站声明: 1. iCode9 技术分享网(下文简称本站)提供的所有内容,仅供技术学习、探讨和分享;
2. 关于本站的所有留言、评论、转载及引用,纯属内容发起人的个人观点,与本站观点和立场无关;
3. 关于本站的所有言论和文字,纯属内容发起人的个人观点,与本站观点和立场无关;
4. 本站文章均是网友提供,不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属;如您发现该文章侵犯了您的权益,可联系我们第一时间进行删除;
5. 本站为非盈利性的个人网站,所有内容不会用来进行牟利,也不会利用任何形式的广告来间接获益,纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。

专注分享技术,共同学习,共同进步。侵权联系[81616952@qq.com]

Copyright (C)ICode9.com, All Rights Reserved.

ICode9版权所有