首页 建站教程 正文
我要投稿

.NET Core利用swagger进行API接口文档管理的方法详解

建站教程
2025-05-29 0 25
也想出现在这里？点击联系我~

一、问题背景

随着技术的发展，现在的开发模式已经更多的转向了前后端分离的模式，在前后端开发的过程中，联系的方式也变成了API接口，但是目前项目中对于API的管理很多时候还是通过手工编写文档，每次的需求变更只要涉及到接口的变更，文档都需要进行额外的维护，如果有哪个小伙伴忘记维护，很多时候就会造成一连续的问题，那如何可以更方便的解决API的沟通问题？Swagger给我们提供了一个方式，由于目前主要我是投入在.NET Core项目的开发中，所以以.NET Core作为示例

二、什么是Swagger

Swagger可以从不同的代码中，根据注释生成API信息，swagger拥有强大的社区，并且对于各种语言都支持良好，有很多的工具可以通过swagger生成的文件生成API文档

三、.NET Core中使用

.NET Core中使用首先要用nuget引用Swashbuckle.AspNetCore，在startup.cs中加入如下代码

?

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31
// This method gets called by the runtime. Use this method to add services to the container.

public void ConfigureServices(IServiceCollection services)

{

services.AddMvc();

services.AddSwaggerGen(c =>

{

c.SwaggerDoc("v1", new Info { csharp\" id=\"highlighter_699906\">

?

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85
using System;

using System.Collections.Generic;

using System.Linq;

using System.Threading.Tasks;

using Microsoft.AspNetCore.Mvc;

namespace WebApplication2.Controllers

{

/// <summary>

/// 测试信息

/// </summary>

[Route("api/[controller]/[action]")]

public class ValuesController : Controller

{

/// <summary>

/// 获取所有信息

/// </summary>

/// <returns></returns>

[HttpGet]

public IEnumerable<string> Get()

{

return new string[] { "value1", "value2" };

}

/// <summary>

/// 根据ID获取信息

/// </summary>

/// <param name="id"></param>

/// <returns></returns>

// GET api/values/5

[HttpGet("{id}")]

public string Get(int id)

{

return "value";

}

/// <summary>

/// POST了一个数据信息

/// </summary>

/// <param name="value"></param>

// POST api/values

[HttpPost]

public void Post([FromBody]string value)

{

}

/// <summary>

/// 根据ID put 数据

/// </summary>

/// <param name="id"></param>

/// <param name="value"></param>

// PUT api/values/5

[HttpPut("{id}")]

public void Put(int id, [FromBody]string value)

{

}

/// <summary>

/// 根据ID删除数据

/// </summary>

/// <param name="id"></param>

// DELETE api/values/5

[HttpDelete("{id}")]

public void Delete(int id)

{

}

/// <summary>

/// 复杂数据操作

/// </summary>

/// <param name="id"></param>

// DELETE api/values/5

[HttpPost]

public namevalue test(namevalue _info)

{

return _info;

}

}

public class namevalue

{

/// <summary>

/// name的信息

/// </summary>

public String name { get; set; }

/// <summary>

/// value的信息

/// </summary>

public String value { get; set; }

}

}

接下来我们还需要在生成中勾上XML生成文档，如图所示

.NET Core利用swagger进行API接口文档管理的方法详解

接下去我们可以运行起来了，调试，浏览器中输入http://localhost:50510/swagger/，这里端口啥的根据实际情况来，运行效果如下图所示：

.NET Core利用swagger进行API接口文档管理的方法详解

可以看到swagger将方法上的注释以及实体的注释都抓出来了，并且显示在swaggerui，整体一目了然，并且可以通过try it按钮进行简单的调试，但是在具体项目中，可能存在需要将某些客户端信息通过header带到服务中，例如token信息，用户信息等（我们项目中就需要header中带上token传递到后端），那针对于这种情况要如何实现呢？可以看下面的做法

?

1

2

3

4

5

6

7

8

9

10

11

12

13

14
// This method gets called by the runtime. Use this method to add services to the container.

public void ConfigureServices(IServiceCollection services)

{

services.AddMvc();

services.AddSwaggerGen(c =>

{

c.SwaggerDoc("v1", new Info { csharp\" id=\"highlighter_96448\">

?

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18
public class AddAuthTokenHeaderParameter : IOperationFilter

{

public void Apply(Operation operation, OperationFilterContext context)

{

if (operation.Parameters == null)

{

operation.Parameters = new List<IParameter>();

}

operation.Parameters.Add(new NonBodyParameter()

{

Name = "token",

In = "header",

Type = "string",

Description = "token认证信息",

Required = true

});

}

}

我们在ConfigureServices添加了OperationFilter<AddAuthTokenHeaderParameter>() ，通过这种方式我们可以在swagger中显示token的header，并且进行调试（如图所示），AddAuthTokenHeaderParameter 的apply的属性context中带了controller以及action的各种信息，可以配合实际情况使用

.NET Core利用swagger进行API接口文档管理的方法详解

四、与其他API管理工具结合

swagger强大的功能以及社区的力量，目前很多的API管理工具都支持YApi，目前我们使用的是由去哪儿开源的YApi，从图中可以看到YApi支持导入swagger生成的JSON文件，除该工具 之外DOClever（开源）也是一个不错的API管理工具，也支持Swagger文件导入（具体工具用法，大家可以去看他们的官网）

.NET Core利用swagger进行API接口文档管理的方法详解

源码下载：demo地址

五、总结

Swagger是一个很好的工具，并且在前后端分离开发越来越流行的情况下，在后续的开发过程中，我觉得会扮演着越来越重要的作用，目前我们公司小的项目已经准备开始使用swagger+yapi进行API的管理方式，而这篇文章也是这段时间抽空整理API管理的结果，希望可以帮助到大家，这里可能有很多不足的地方，欢迎大家拍砖，也希望可以跟大家一起进步

以上就是这篇文章的全部内容了，希望本文的内容对大家的学习或者工作具有一定的参考学习价值，如果有疑问大家可以留言交流，谢谢大家对快网idc的支持。

原文链接：http://www.cnblogs.com/OMango/p/8460092.html

收藏 (0) 打赏

感谢您的支持，我会继续努力的!

打开微信/支付宝扫一扫，即可进行扫码打赏哦，分享从这里开始，精彩与您同在
点赞 (0)

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。

快网idc优惠网 建站教程 .NET Core利用swagger进行API接口文档管理的方法详解 https://www.kuaiidc.com/98577.html

也想出现在这里？点击联系我~

相关文章

ASP.NET自助建站系统中的用户注册和登录功能定制方法
ASP.NET自助建站系统中的用户注册和登录功能定制方法
建站教程
5个月前 157
ASP.NET自助建站系统的域名绑定与解析教程
ASP.NET自助建站系统的域名绑定与解析教程
建站教程
5个月前 130
个人服务器网站搭建：如何选择合适的服务器提供商？
个人服务器网站搭建：如何选择合适的服务器提供商？
建站教程
5个月前 89
ASP.NET自助建站系统中如何实现多语言支持？
ASP.NET自助建站系统中如何实现多语言支持？
建站教程
5个月前 122
猜你喜欢
发表评论
暂无评论
TA的动态
快网idc优惠网

idc信息共同学习，共同进步，共同成长！

QQ交流群
快网idc优惠网

QQ交流群

您的支持，是我们最大的动力！
热门文章
热门评论
终身VIP会员限时钜惠
首页 SSL证书 菜单 论坛 问答