.NET Core使用swagger进行API接口文档管理

一、问题背景

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

二、什么是Swagger

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

三、.NET Core中使用

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

        // 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 { Title = "Hello", Version = "v1" });
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "WebApplication2.xml");
                c.IncludeXmlComments(xmlPath);
            });
            services.AddMvcCore().AddApiExplorer();
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseMvcWithDefaultRoute();
            app.UseSwagger(c =>
            {
            });
            app.UseSwaggerUI(c =>
            {
                c.ShowExtensions();
                c.ValidatorUrl(null);
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "test V1");
            });
        }

  以上部分为加载swagger的代码,位于startup.cs中,下面是controller代码:

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生成文档,如图所示

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

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

// 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 { Title = "Hello", Version = "v1" });
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "WebApplication2.xml");
                c.IncludeXmlComments(xmlPath);
                c.OperationFilter<AddAuthTokenHeaderParameter>();
            });
            services.AddMvcCore().AddApiExplorer();
        }
    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的各种信息,可以配合实际情况使用

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

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

五、总结

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

  demo地址

原文地址:https://www.cnblogs.com/duanweishi/p/9410867.html

时间: 2024-10-11 21:06:06

.NET Core使用swagger进行API接口文档管理的相关文章

Api接口文档管理工具,你知道哪些呢?

上周看到有人在我的Github开源项目中提了个issue,说是否考虑接入swagger.那今天我就用swagger与其他接口文档工具做对比,同时说说Api接口文档工具的那点事.如今,在前后端分离开发的这个年代,Api接口文档管理工具越来越显得重要.完整的Api接口文档能大大提升前后端开发协作的效率. image 目前市场有哪些比较优秀的接口文档管理工具呢?Swagger Api接口文档工具到底如何,我大致汇总一下吧! 一.Swagger 说到Swagger,他确实是为开发者发明的一款神器,他可以

Spring Cloud Zuul中使用Swagger汇总API接口文档

有很多读者问过这样的一个问题:虽然使用Swagger可以为Spring MVC编写的接口生成了API文档,但是在微服务化之后,这些API文档都离散在各个微服务中,是否有办法将这些接口都整合到一个文档中? 如果您还不了解Spring Cloud Zuul和Swagger,建议优先阅读下面两篇,有一个初步的了解: Spring Cloud构建微服务架构:服务网关(基础) Spring Boot中使用Swagger2构建强大的RESTful API文档 准备工作 上面说了问题的场景是在微服务化之后,所

Dokuwiki API接口文档管理中文支持更改

1.文件 \conf\local.php 增加$conf['fnencode'] = 'gbk';如果存就更改 2.文件 \inc\pageutils.php function utf8_encodeFN($file,$safe=true){ global $conf; if($conf['fnencode'] == 'utf-8') return $file; if($safe && preg_match('#^[a-zA-Z0-9/_\-\.%]+$#',$file)){ return

用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档

博客搬到了fresky.github.io - Dawei XU,请各位看官挪步.最新的一篇是:用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档.

Swagger UI教程 API 文档神器 搭配Node使用 web api 接口文档 mvc接口文档

两种方案 一.Swagger 配置 web Api 接口文档美化 二.通过NodeJS 发布Swagger UI 配置api 文档 先说一下简单的 Swagger 配置 web Api  Swagger-UI本身只提供在线测试功能,要集成它还需要告诉它本项目提供的各种服务和参数信息.这里就需要一些工作量了,不过好在许多第三方库已经给我们完成了这一工作.我这里用的是Swashbuckle,使用它也比较简单,直接使用Nuget添加其程序包即可: 1.初始化包  PM> Install-Package

构建标准OpenStack API接口文档

1.构建API接口文档标准参考: http://docs.openstack.org/contributor-guide/api-guides.html 2.构建API接口文档步骤参考下面的Patch: https://review.openstack.org/#/c/361791/ https://review.openstack.org/#/c/305870/ https://review.openstack.org/#/c/305973/ 3.创建API接口文档的CI已经如何发布到Open

SpringBoot + Swagger2 自动生成API接口文档

spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口.这些接口不但会服务于传统的web端(b/s),也会服务于移动端.在实际开发过程中,这些接口还要提供给开发测试进行相关的白盒测试,那么势必存在如何在多人协作中共享和及时更新API开发接口文档的问题. 假如你已经对传统的wiki文档共享方式所带来的弊端深恶痛绝,那么尝试一下Swagger2 方式,一定会让你有不一样的开发体验: 功能丰富 :支持多种注解,自动生成接

app后端开发二:API接口文档工具

悲伤的历史 在进行app后端开发过程中,后端会提供出来很多的api接口供前端开发使用,为了让前端开发人员顺利使用,我们会写好一份文档,告诉他们这个接口你该用 GET 还是 POST 来访问,同时访问的时候该给我传递一些什么参数,以及正确的时候我会返回什么给你,已经返回的数据样式以及字段解释等等这些事情,我们都需要在文档中写好写清楚. 在 app后端开发一:基于swagger-ui构建api接口文档工具 这篇博客中,我写了 swagger-ui 的好处以及优势.但是在使用过程中,发现不够给力.我想

关于api接口文档RAP和swagger

前言: 在之前的项目中用了将近一年的RAP,RAP是由阿里开源出来的,非常好用.github地址:https://github.com/thx/RAP. 当初在用此工具时,项目成员需要在接口文档在所改动后,发邮件到项目组成员,由于rap当时没有此功能,所以还下载源码,增加了发邮件功能. 将此功能代码commit到了社区,好像社区没有接纳合入. 后来使用了一年后,发现了swagger似乎使用很方便,直接跟代码进行结合,需要重新使用其他工具进行配合了. 所以以下时对swagger的spring集成说