(一).NET Core WebAPI集成Swagger做接口管理

简介: 什么是Swagger?Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测。Swagger 有什么优势?支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需

什么是Swagger?

Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测。

Swagger 有什么优势?

支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。

提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。

在.NET Core中如何使用Swagger?

(1)准备工作

创建一个.NET Core WebApi 项目

创建一个Model类库

(2)在项目中引入Swagger

在WebApi项目中执行命令:Install-package Swashbuckle.AspNetCore

image.png

(3)在StarUp.cs的ConfigureServices中添加代码

#region Swagger

           services.AddSwaggerGen(c =>

           {

               c.SwaggerDoc("v1", new Info

               {

                   Version = "v1.1.0",

                   Title = "Swagger WebAPI",

                   Description = "XXX项目API文档",

                   TermsOfService = "None",

                   Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "XXX项目", Email = "273145719@qq.com"

                   , Url = "https://www.cnblogs.com/NBIDataVis/" }

               });

               var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);

               //添加接口XML的路径

               var xmlPath = Path.Combine(basePath, "TrySwaggerCore.xml");

               //如果需要显示控制器注释只需将第二个参数设置为true

               c.IncludeXmlComments(xmlPath, true);

           });

#endregion

(4)在StarUp.cs的Configure中添加代码

#region Swagger

app.UseSwagger();

app.UseSwaggerUI(c =>

{

 c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiDocument V1");

});

#endregion

 

(5)运行后进入/swagger目录 即可查看Swagger已经启用

image.png

image.png

问题汇总:

(1)如果需要将WebApi的默认启动页设为Swagger则在Properties中

image.png

(2)在这里大家会发现运行后接口的注释并没有显示,我们需要配置注释XML文件

image.png

在WebAPI项目上点击右键-》属性-》生成-》XML文档文件

另外切记此处代码第二个参数需要设置为True,否则将不显示控制器级别的注释,只显示接口注释

image.png

(3)如果大家会发现有了许多警告,强迫症患者看这里,我们只需要在生成中强制过滤1591的警告即可

image.png

下一章给大家介绍Swagger的分组功能用法。

相关文章
|
3月前
|
JSON Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
本文详细介绍了Swagger2的使用方法,包括在Spring Boot项目中的配置与应用。重点讲解了Swagger2中常用的注解,如实体类上的`@ApiModel`和`@ApiModelProperty`,Controller类上的`@Api`、`@ApiOperation`以及参数上的`@ApiParam`等。通过示例代码展示了如何为实体类和接口添加注解,并在页面上生成在线接口文档,实现接口测试。最后总结了Swagger的优势及其在项目开发中的重要性,提供了课程源代码下载链接供学习参考。
111 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
|
3月前
|
缓存 Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
本文介绍了在Spring Boot中配置Swagger2的方法。通过创建一个配置类,添加`@Configuration`和`@EnableSwagger2`注解,使用Docket对象定义API文档的详细信息,包括标题、描述、版本和包路径等。配置完成后,访问`localhost:8080/swagger-ui.html`即可查看接口文档。文中还提示了可能因浏览器缓存导致的问题及解决方法。
127 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
|
3月前
|
Java Maven 微服务
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的 maven 依赖
在项目中使用Swagger2工具时,需导入Maven依赖。尽管官方最高版本为2.8.0,但其展示效果不够理想且稳定性欠佳。实际开发中常用2.2.2版本,因其稳定且界面友好。以下是围绕2.2.2版本的Maven依赖配置,包括`springfox-swagger2`和`springfox-swagger-ui`两个模块。
77 0
|
3月前
|
前端开发 Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档—— Swagger 简介
第6课介绍了在Spring Boot中集成Swagger2以展示在线接口文档的方法。随着前后端分离架构的发展,API文档成为连接前端与后端开发的重要纽带。然而,代码更新频繁导致文档难以同步维护,Swagger2解决了这一问题。通过Swagger,在线API文档不仅方便了接口调用方查看和测试,还支持开发者实时测试接口数据。本文使用Swagger 2.2.2版本,讲解如何在Spring Boot项目中导入并配置Swagger2工具,从而高效管理接口文档。
134 0
|
5月前
|
开发框架 .NET API
在 .NET 9 中使用 Scalar 替代 Swagger
在 .NET 9 中使用 Scalar 替代 Swagger
135 29
|
7月前
|
人工智能 API C#
使用Microsoft.Extensions.AI简化.NET中的AI集成
使用Microsoft.Extensions.AI简化.NET中的AI集成
157 5
使用Microsoft.Extensions.AI简化.NET中的AI集成
|
6月前
|
开发框架 缓存 .NET
GraphQL 与 ASP.NET Core 集成:从入门到精通
本文详细介绍了如何在ASP.NET Core中集成GraphQL,包括安装必要的NuGet包、创建GraphQL Schema、配置GraphQL服务等步骤。同时,文章还探讨了常见问题及其解决方法,如处理复杂查询、错误处理、性能优化和实现认证授权等,旨在帮助开发者构建灵活且高效的API。
149 3
|
8月前
|
开发框架 .NET API
Windows Forms应用程序中集成一个ASP.NET API服务
Windows Forms应用程序中集成一个ASP.NET API服务
160 9
|
8月前
|
前端开发 Java 程序员
springboot 学习十五:Spring Boot 优雅的集成Swagger2、Knife4j
这篇文章是关于如何在Spring Boot项目中集成Swagger2和Knife4j来生成和美化API接口文档的详细教程。
1113 1
|
9月前
|
开发工具 Python
django之drf集成swagger
django之drf集成swagger

热门文章

最新文章