文章详情

短信预约-IT技能 免费直播动态提醒

请输入下面的图形验证码

提交验证

短信预约提醒成功

ASP.NET Core使用Swagger/OpenAPI规范

2024-04-02 19:55

关注

1.什么是Swagger/OpenAPI?

Swagger是一个与语言无关的规范,用于描述REST API。因为Swagger项目已捐赠给OpenAPI计划,所以也叫OpenAPI。它允许计算机和人员了解服务的功能,可以直接在线访问测试API方法。而Swagger UI提供了基于Web的UI,它使用生成的Swagger规范提供有关服务API的信息。Swashbuckle和NSwag均包含Swagger UI的嵌入式版本,因此可使用中间件注册调用将该嵌入式版本托管在ASP.NET Core应用程序当中。Swagger的核心是Swagger规范,默认情况下是名为swagger.json的文档。它由Swagger工具链(或其第三方实现)根据你的服务生成。它描述了API的功能以及使用HTTP对其进行访问的方式。它驱动Swagger UI,并由工具链用来启用发现和客户端代码生成。

2.NET Swagger实现

NET Swagger实现分为两大分类:

但是由于工作比较忙,我就不打算两个类型都讲了,我只选择Swashbuckle.AspNetCore来讲解和演示。

3.Swashbuckle主要组成部分

Swashbuckle有三个主要组成部分:

安装Swashbuckle组件方法有两种:

--PowerShell
Install-Package Swashbuckle.AspNetCore -Version 5.0.0

or

--.NET Core CLI
dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 5.0.0

4.什么是REST?

我百度一下,度娘解释是:REST是(Representational State Transfer)“表现层状态转移”的缩写,它是由罗伊·菲尔丁(Roy Fielding)提出的,是用来描述创建HTTP API的标准方法,他发现这四种常用的行为“查看(view),创建(create),编辑(edit)和删除(delete)”都可以直接映射到HTTP中已实现的GET、POST、PUT和DELETE方法。

5.配置Swagger中间件

将Swagger生成器添加到Startup.ConfigureServices方法中的服务集合中:

//注册Swagger生成器,定义一个或多个Swagger文档.
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1", Description = "测试描述" });
});

OpenApiInfo对象是用来标识Swagger文档信息(诸如作者、许可证和说明的信息),您还可以自定义您的主题的信息显示在UI上,详情配置,我就不多说,大家可以看官网描述,如上述OpenApilnfo信息配置示例图:

而在启动应用程序后并导航到http://localhost:<port>/swagger/v1/swagger.json。生成的描述终结点的文档显示在Swagger规范(swagger.json)中:

在Startup.Configure方法中,启用中间件为生成的JSON文档和Swagger UI提供服务:

//使中间件能够将生成的Swagger用作JSON端点.
app.UseSwagger();
//允许中间件为swagger ui(HTML、JS、CSS等)提供服务,指定swagger JSON端点.
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

根据上述配置就能够启用swagger测试API服务接口了,如下图所示:

6.XML注释

swagger还可以把服务API中对应方法名称,实体属性注释给在UI上显示出来,让您更加直观了解每个方法使用信息,并对没有注释每个方法进行警告提示,具体启用XML注释操作在“解决方案资源管理器”中右键单击该项目,然后选择“编辑<project_name>.csproj”,手动将突出显示的行添加到.csproj 文件:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

在启用了XML注释后,swagger只会针对没有添加注释每个方法进行警告提示,而添加了注释的方法则不会进行警告提示:

而每个添加了注释的方法会通过在Startup.ConfigureServices/services.AddSwaggerGen中设置Swagger JSON和UI的注释路径后:

//设置Swagger JSON和UI的注释路径.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);

会在项目根目录生成的一个对应项目文件名的XML文件,而文件里面就包含所有已注释的方法,用于UI上显示:

在启动应用程序后,我们会看到每个有注释方法在左侧会有一行文字描述,效果如下图所示:

如果某个方法或者类下面所有方法不想警告提示,可以通过加入#pragma warning disable声明屏蔽警告提示:

加入声明之后,大家会看到警告提示消失了。

7.数据注释

可以使用System.ComponentModel.DataAnnotations命名空间中的属性来标记模型实体,以帮助驱动Swagger UI 组件。将[Required]属性添加到TodoItem类的Name属性:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        [Required]
        public string Name { get; set; }
        [DefaultValue(false)]
        public bool IsComplete { get; set; }
    }
}

此属性的状态会更改掉基础JSON架构:

而将[Produces("application/json")]属性添加到API控制器去,这样做的目的是声明控制器的操作支持application/json的响应内容类型:

[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    /// <summary>
    /// 获取值
    /// </summary>
    /// <returns></returns>
    // GET api/values
    [HttpGet]
    public async Task<ActionResult<IEnumerable<string>>> Get()
    {
        var result = await new GitHubApi().GetUser();
        return new string[] { result.id.Value.ToString(), result.login };
    }
}

“响应内容类型”下拉列表选此内容类型作为控制器的默认GET操作:

Swagger/OpenAPI出现,大大减少开发者调试时间,增加开发者开发效率,让开发者更加方便调试跟直观了解对应服务方法。

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持编程网。

阅读原文内容投诉

免责声明:

① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的,并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据,供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。

② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341

软考中级精品资料免费领

  • 历年真题答案解析
  • 备考技巧名师总结
  • 高频考点精准押题
  • 2024年上半年信息系统项目管理师第二批次真题及答案解析(完整版)

    难度     813人已做
    查看
  • 【考后总结】2024年5月26日信息系统项目管理师第2批次考情分析

    难度     354人已做
    查看
  • 【考后总结】2024年5月25日信息系统项目管理师第1批次考情分析

    难度     318人已做
    查看
  • 2024年上半年软考高项第一、二批次真题考点汇总(完整版)

    难度     435人已做
    查看
  • 2024年上半年系统架构设计师考试综合知识真题

    难度     224人已做
    查看

相关文章

发现更多好内容

猜你喜欢

AI推送时光机
位置:首页-资讯-后端开发
咦!没有更多了?去看看其它编程学习网 内容吧
首页课程
资料下载
问答资讯