首页 > 其他分享 >Api文档 swagger整合

Api文档 swagger整合

时间:2023-01-09 07:44:05浏览次数:52  
标签:服务 静淡 Api 文档 2022 net swagger

微服务系列之Api文档 swagger整合

 

1.前言

  微服务架构随之而来的前后端彻底分离,且服务众多,无论是前后端对接亦或是产品、运营翻看,一个现代化、规范化、可视化、可尝试的文档是多么重要,所以我们这节就说说swagger。

  Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

  swagger优势:

  1)后端开发人员,不在重复的用wiki或word不断改来改去;

  2).net core集成简单,无侵入性,开发人员只需要使用.net自身的注释即可;

2.实战

  新建一个.net core3.1项目,nuget安装Swashbuckle.AspNetCore包最新版本

  DI注入

  

复制代码
 services.AddSwaggerGen(e =>
            {
                e.SwaggerDoc("v1",
                    new Microsoft.OpenApi.Models.OpenApiInfo()
                    {
                        Title = "MySwaggerService1 API",//文档标题
                        Version = "v1"//文档版本
                    }
                    );
                //e.OperationFilter<AddAuthTokenFilter>();
                e.IncludeXmlComments(System.IO.Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "MySwaggerService1.xml"));//swagger会自动生成文档xml文件,指定位置来加载
                //e.IncludeXmlComments(System.IO.Path.Combine(Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationBasePath, "xxxxx.xml"));//注释的这里,swagger会为每个类库都生成类库名.xml的配置文件,我这里只有一个简单的demo,所以不用
            });
复制代码

添加中间件

app.UseSwagger()
               .UseSwaggerUI(c =>
               {
                   c.SwaggerEndpoint($"/swagger/v1/swagger.json", "MySwaggerService1");
               });

项目右键属性=》生成,将debug和release配置下,输出=》输出路径=》xml文档位置,勾选,默认即可。

写一个get接口,写一个post接口。

复制代码
  [Route("api/[controller]")]
    [ApiController]
    public class DemoController : ControllerBase
    {
        /// <summary>
        /// 我的接口
        /// </summary>
        /// <param name="no">我的参数</param>
        /// <returns></returns>
        [ProducesResponseType(typeof(string), (int)HttpStatusCode.OK)]
        [ProducesResponseType(typeof(string), (int)HttpStatusCode.BadRequest)]
        [HttpGet("my")]
        public async Task<IActionResult> My([FromQuery] string no)
        {
            return Ok("hello docker");
        }

        /// <summary>
        /// 我的第二个接口
        /// </summary>
        /// <param name="queryModel"></param>
        /// <returns></returns>
        [ProducesResponseType(typeof(List<MyViewModel>), (int)HttpStatusCode.OK)]
        [ProducesResponseType(typeof(string), (int)HttpStatusCode.BadRequest)]
        [HttpPost("query/my")]
        public async Task<IActionResult> PostMy([FromBody] MyQueryModel queryModel)
        {
            var res = new List<MyViewModel>();
            res.Add(new MyViewModel() { 
                Gid = "1",
                MyList = new List<int>() { 1,2,3}
            });
            return Ok(res);
        }
    }
复制代码

启动后:地址 http://localhost:xxxx/swagger.

到此,.net core集成swagger结束。

3.swagger切换

  上文这个服务的在线文档已经好了,如果10个服务的话,想要查看,就要打开10个地址,而微服务系统可远不止10个那么少,所以我们要用一个统一地址,可以选择服务进行自由切换。配置如下:

  我们已经建立了一个服务,并且配置好了swagger,我们在新建一个一样的服务,并且一样配置好swagger,并且写2个接口

  再新建一个服务,做为swagger统一入口服务,一样引入nuget包,DI注入也是一样的,只需要在添加中间件的时候利用swagger的SwaggerUIOptions的扩展SwaggerEndpoint,就可以集中配置,如代码

  

复制代码
 var apis = new List<string>();
            apis.Add("http://localhost:5001");
            apis.Add("http://localhost:5002");
           
            app.UseSwagger()
            .UseSwaggerUI(c =>
            {
                apis.ForEach(m =>
                {
                    c.SwaggerEndpoint($"{m}/swagger/v1/swagger.json", m);
                });
            });
复制代码

然后,三个服务同时启动,打开这个统一文档服务的swagger地址如下图:

看右上角,可以切换服务定义了,这回方便了。回到统一服务的,中间件配置的代码上,因为人家是endpoint,是地址,所以我们只能如此简陋的配置,在切换地方显示的是地址,真实项目中,这样肯定不行的,首先开发人员要知道所有服务地址是不显示的,其次通过地址切换,你也不知道服务是干啥的,所以实际项目中,我们是利用网关+consul+配置中心的地址规则,来集中配置。如下图

最后的统一文档服务的目标切换,就是服务名称

微服务系列之服务监控 Prometheus与Grafana 摘要:1.为什么需要监控服务 监控服务的所属服务器硬件(如cpu,内存,磁盘I/O等)指标、服务本身的(如gc频率、线程池大小、锁争用情况、请求、响应、自定义业务指标),对于以前的小型单体服务来说,确实没什么必要,但对于中大型项目,尤其那些群集部署显得尤为重要、尤其是现在的微服务架构,服务众多,而且很多服 阅读全文 posted @ 2022-12-20 17:17 CL静淡 阅读(287) 评论(0) 推荐(2) 编辑   微服务系列之服务注册发现 Consul 摘要:1.为什么需要服务注册与发现 微服务架构中,服务于服务之间内部通信必不可少,比如A服务调用B服务,起初我们的做法是,A服务从配置文件中拿到B服务的IP、端口地址,进行访问,本身是没什么问题的,但是随着业务的复杂性越来越高,会遇到一个最蛋疼的问题,服务A可能依赖很多其他服务,这样就要维护好多个服务的地 阅读全文 posted @ 2022-11-25 23:46 CL静淡 阅读(341) 评论(0) 推荐(2) 编辑   微服务系列之配置中心 Apollo 摘要:1.背景与介绍 随着微服务架构的发展,企业级项目由无数的服务组成,这时候急需用到集中管理、治理的配置的组件,来统一管理各个服务的开关、配置参数、数据库地址、服务器等等,然而这还不够,还要对这个管理配置的组件有着修改后实时发布、多环境、灰度发布、权限控制、审核等等机制,由此配置中心出现了,而由携程开源 阅读全文 posted @ 2022-11-09 15:34 CL静淡 阅读(110) 评论(0) 推荐(0) 编辑   微服务系列之分布式日志 ELK 摘要:1.ELK简介 ELK是ElasticSearch+LogStash+Kibana的缩写,是现代微服务架构流行的分布式日志解决方案,旨在大规模服务的日志集中管理查看,极大的为微服务开发人员提供了排查生产环境的便利。如果规模较小的日志量,直接使用ElasticSearch、Logstash、Kiban 阅读全文 posted @ 2022-10-21 15:50 CL静淡 阅读(669) 评论(2) 推荐(3) 编辑   微服务系列之Api文档 swagger整合 摘要:1.前言 微服务架构随之而来的前后端彻底分离,且服务众多,无论是前后端对接亦或是产品、运营翻看,一个现代化、规范化、可视化、可尝试的文档是多么重要,所以我们这节就说说swagger。 Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用 阅读全文 posted @ 2022-09-23 16:04 CL静淡 阅读(706) 评论(1) 推荐(2) 编辑   微服务系列之授权认证(三) JWT 摘要:1.JWT简介 官方定义:JWT是JSON Web Token的缩写,JSON Web Token是一个开放标准(RFC 7519),它定义了一种紧凑的、自包含的方式,可以将各方之间的信息作为JSON对象安全地传输。该信息可以被验证和信任,因为它是经过加密的。 实际上,Oauth2.0中的acces 阅读全文 posted @ 2022-09-21 15:28 CL静淡 阅读(987) 评论(0) 推荐(2) 编辑   微服务系列之授权认证(二) identity server 4 摘要:1.简介 IdentityServer4 是为ASP.NET Core系列量身打造的一款基于 OpenID Connect 和 OAuth 2.0 认证授权框架。 官方文档:https://identityserver4.readthedocs.io/en/latest/ 框架源码:https:// 阅读全文 posted @ 2022-09-20 18:02 CL静淡 阅读(581) 评论(1) 推荐(1) 编辑   微服务系列之授权认证(一) OAuth 2.0 和 OpenID Connect 摘要:1.传统架构的授权认证 传统应用架构,用户使用账号密码登录后,可以使用前端cookie存储登录状态,也可以使用后端session方式存储登录状态,小应用这么做其实很高效实用,当应用需要横向扩展时,就需要共享登录状态,这时候session的基于asp.net state这种当前服务器进程方式存储就失效 阅读全文 posted @ 2022-09-15 18:27 CL静淡 阅读(630) 评论(1) 推荐(2) 编辑   微服务系列之网关(二) konga配置操作 摘要:1.konga核心对象 Kong 的四大核心对象:upstream,target,service,route。下面分别说: (1)upstream,字面意思上游,实际项目理解是对某一个服务的一个或者多个请求地址的抽象入口,新建upstream可配置基本信息,被动/主动健康检查。 (2)trarget 阅读全文 posted @ 2022-09-07 11:32 CL静淡 阅读(746) 评论(0) 推荐(0) 编辑   微服务系列之网关(一) kong及管理界面konga的安装部署 摘要:1.网关概述 微服务架构系统少则十几,多则成百上千个服务组成,除了少部分内部基础服务之外,大部分都是客户端调用,在没有网关之前,客户端需要把所用到的服务,都配置到一个配置文件里,少的时候还行,多的时候,维护起来相当麻烦,容易出错,尤其服务地址发生迁移变化的时候,这时候网关最实用也最常用的功能就体现出 阅读全文 posted @ 2022-09-06 15:23 CL静淡 阅读(644) 评论(0) 推荐(0) 编辑   .net core微服务系列之前言 摘要:微服务概念其实已经流行了不短的年头了,只是大部分实战都是在以java为主的大型互联网公司使用,.net在国内的市场,作为.net程序猿们都懂得,就拿北京来说,前2年别说微服务了,就连.net core用的公司都不是很多,很多人躺平到asp.net了,但是随着.net core把版本不断更新,社区也不 阅读全文 posted @ 2022-09-01 18:14 CL静淡 阅读(76) 评论(0) 推荐(0) 编辑

标签:服务,静淡,Api,文档,2022,net,swagger
From: https://www.cnblogs.com/Leo_wl/p/17035954.html

相关文章