ASP.NET Core Web API中使用Swagger

本节导航

  • Swagger介绍
  • 在ASP.NET CORE 中的使用swagger

??在软件开发中,管理和测试API是一件重要而富有挑战性的工作。在我之前的文章《研发团队,请管好你的API文档》也专门阐述了通过文档管理工具,来保证API文档和代码的一致性,这样更加有助于团队的协作。

??以往我们总是通过第三方平台工具来管理我们的API文档,如eolinker。在测试方面,我们也会依赖fiddler,PostMan这样的工具。

??Swagger兼具了API文档管理和测试的功能,而且保证了代码和文档的一致性。它提供了无需任何实现逻辑的RESTfulAPI的UI表示。它允许用户在没有任何代码访问的情况下了解服务的功能，并减少创建服务文档的时间。

1 Swagger介绍

??Swagger兼具了API文档管理和测试的功能,而且保证了代码和文档的一致性。它提供了无需任何实现逻辑的RESTfulAPI的UI表示。它允许用户在没有任何代码访问的情况下了解服务的功能，并减少创建服务文档的时间。

??swagger使用swagger工具基于我们编写的服务代码生成的swagger.json文件来生成文档管理界面。此文件描述服务的功能，即服务支持多少方法，并提供有关方法参数的信息。使用这个文件，SwaggerUI生成客户机代码。下面是swagger.json文件的一个示例。

{
    "swagger": "2.0",
    "info": {
        "version": "1.0",
        "title": "My Demo API"
    },
    "paths": {
        "/api/Values": {
            "get": {
                "tags": ["Values"],
                "summary": "Get values",
                "operationId": "Get",
                "consumes": [],
                "produces": ["text/plain", "application/json", "text/json"],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success",
                        "schema": {
                            "uniqueItems": false,
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": ["Values"],
                "operationId": "Post",
                "consumes": ["application/json-patch+json", "application/json", "text/json", "application/*+json"],
                "produces": [],
                "parameters": [{
                    "name": "value",
                    "in": "body",
                    "required": false,
                    "schema": {
                        "type": "string"
                    }
                }],
                "responses": {
                    "200": {
                        "description": "Success"
                    }
                }
            }
        }
    },
    "definitions": {}
}

??在APS.NET Core Web API 中，我们可以用Swashbuckle.AspNetCore 和 NSwag这两个包来实现Swagger,而且二者都是github上开源的。此外，nswag还提供了生成typescript客户端代码的方法以及用于API的服务代码。

1.2 TPL

??任务并行库（TPL）是System.Threading和System.Threading.Tasks命名空间中的一组公共类型和API。

??TPL动态地扩展并发度，以最有效地使用所有可用的处理器。通过使用TPL，您可以最大限度地提高代码的性能，同时专注于您的代码的业务实现。

??从.NET Framework 4开始，TPL是编写多线程和并行代码的首选方式。

2 在ASP.NET CORE 中的使用swagger

??这里以Swashbuckle.AspNetCore来实现。

??以下是在ASP.net Core Web API中配置Swagger的步骤:

1. 安装Swashbuckle.AspNetCore

PM> Install-Package Swashbuckle.AspNetCore

2. 配置swagger中间件

??要将swagger middle添加到请求管道，需要在startup类的configureService方法中添加swaggergen方法。在这里，我们可以定义一个或多个swagger XML文档。

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().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1.0", new Info { Title = "My Demo API", Version = "1.0" });
                c.IncludeXmlComments(System.IO.Path.Combine(System.AppContext.BaseDirectory, "ZhiKeCore.API.xml"));
            });
        }

??如果要启用这个中间件，我们还需要在startup类的configure方法中调用useswagger方法。在这里，我们还需要配置swagerendpoint来生成UI。useswagegrui将添加一个静态文件中间件来加载swager.json文件。

// 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();
            }
            else
            {
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseMvc();

            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1.0/swagger.json", "My Demo API (V 1.0)");
            });
        }

??以上是配置swagger的基本步骤,如果我们想使用Visual Studio在开发环境中启动Swagger，还需要做一点设置。选择项目-属性-Debug,修改启动浏览器(Launch Browser)的值为swagger。

??当我们启动程序以后,可以看到如下界面:

??正如我们在这里看到的，它对每个HTTP动词使用不同的颜色代码。当我们单击任何操作方法时，它将询问参数详细信息，当我们单击“非常”按钮时，它将向Web API发送请求。

??在测试我们的WebAPI时，Swagger只需要最少的配置即可。

??那么，如果我们想要在UI上显示代码注释应该怎么办呢？

??在.NET Core中，我们可以通过在项目属性窗口的“构建”选项卡下设置“XML文档文件”属性来获取XML注释。

??默认情况下，Swagger UI不显示此文档。我们需要传递包含exmlcomments的路径。

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
       // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1.0", new Info { Title = "My Demo API", Version = "1.0" });
                c.IncludeXmlComments(System.IO.Path.Combine(System.AppContext.BaseDirectory, "ZhiKeCore.API.xml"));
            });
        }

参考

关注
??请关注微信公众号智客坊。

原文地址：https://www.cnblogs.com/lucky_hu/p/11130209.html

时间： 2024-10-11 04:38:09

ASP.NET Core Web API中使用Swagger的相关文章

在ASP.NET Core Web API中为RESTful服务增加对HAL的支持

HAL(Hypertext Application Language,超文本应用语言)是一种RESTful API的数据格式风格,为RESTful API的设计提供了接口规范,同时也降低了客户端与服务端接口的耦合度.很多当今流行的RESTful API开发框架,包括Spring REST,也都默认支持HAL规范,当RESTful API被调用后,服务端就会返回ContentType为application/hal+json的JSON内容,例如: { "_links": { "

ASP.NET Core Web API中实现全局异常捕获与处理

处理全局异常 HANDLING ERRORS GLOBALLY 在上面的示例中,我们的 action 内部有一个 try-catch 代码块.这一点很重要,我们需要在我们的 action 方法体中处理所有的异常(包括未处理的).一些开发者在 action 中使用 try-catch 代码块,这种方式明显没有任何问题.但我们希望 action 尽量保持简洁.因此,从我们的 action 中删除 try-catch ,并将其放在一个集中的地方会是一种更好的方式..NET Core 给我们提供了一种处

ASP.NET Core Web API中Startup的使用技巧

Startup类和服务配置   STARTUP CLASS AND THE SERVICE CONFIGURATION 在 Startup 类中,有两个方法:ConfigureServices 是用于服务注册,Configure 方法是向应用程序的请求管道中添加中间件. 因此,最好的方式是保持 ConfigureServices 方法简洁,并且尽可能地具有可读性.当然,我们需要在该方法内部编写代码来注册服务,但是我们可以通过使用 扩展方法 来让我们的代码更加地可读和可维护. 例如,让我们看一个注

Core Web API上使用Swagger提供API文档

在ASP.NET Core Web API上使用Swagger提供API文档 我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页面后,在IISExpress启动Web API站点后,会自动重定向到API文档页面,非常方便.这不仅让我能够快速省查API设计的合理性,同时从API的使用角度也为我自己提供了便捷.下图就是我的博客系统RESTful API

ASP.NET Core Web API下事件驱动型架构的实现（二）：事件处理器中对象生命周期的管理

在上文中,我介绍了事件驱动型架构的一种简单的实现,并演示了一个完整的事件派发.订阅和处理的流程.这种实现太简单了,百十行代码就展示了一个基本工作原理.然而,要将这样的解决方案运用到实际生产环境,还有很长的路要走.今天,我们就研究一下在事件处理器中,对象生命周期的管理问题. 事实上,不仅仅是在事件处理器中,我们需要关心对象的生命周期,在整个ASP.NET Core Web API的应用程序里,我们需要理解并仔细推敲被注册到IoC容器中的服务,它们的生命周期应该是个怎样的情形,这也是服务端应用程序设

ASP.NET Core Web API 开发-RESTful API实现

REST 介绍: 符合REST设计风格的Web API称为RESTful API. 具象状态传输(英文:Representational State Transfer,简称REST)是Roy Thomas Fielding博士于2000年在他的博士论文 "Architectural Styles and the Design of Network-based Software Architectures" 中提出来的一种万维网软件架构风格. 目前在三种主流的Web服务实现方案中,因为R

使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档（ASP.NET Core Web API 自动生成文档）

对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你创建良好的文档和帮助页面. Swashbuckle 可以通过修改 Startup.cs 作为一组 NuGet 包方便的加入项目.Swashbuckle 是一个开源项目,为使用 ASP.NET Core MVC 构建的 Web APIs 生成 Swagger 文档.Swagger 是一个机器可读的 R

使用Swagger来生成asp.net core Web API 文档

对于构建一个消费应用程序,理解API的各个方法对开发这是一个不小的挑战.为了使你的API更利于阅读.使用Swagger为你的Web API生成好的文档和帮助页,.NET Core实现了Swashbuckle.AspNetCore,使用Swagger是非常简单的,只需添加一组Nuget包和修改Startup就可以搞定. .Swashbuckle.AspNetCore 开源项目, ASP.NET Core Web API生成Swagger文档的 .Swagger是一个机器可读的restful风格的a

asp.net core web api 生成 swagger 文档

asp.net core web api 生成 swagger 文档 Intro 在前后端分离的开发模式下,文档就显得比较重要,哪个接口要传哪些参数,如果一两个接口还好,口头上直接沟通好就可以了,如果接口多了就有点不适用了,没有接口文档会大大提高前后端的沟通成本.而 asp.net core 可以通过 Swashbuckle.AspNetCore 很方便的集成 swagger 文档,相比之前 nodejs(express) 和 swagger 集成就很麻烦了,大概这就是强类型语言的优势吧.C#