开发者社区> yanbigfeg> 正文
阿里云
为了无法计算的价值
打开APP
阿里云APP内打开

【WebAPI No.4】Swagger实现API文档功能

简介: 介绍: Swagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案。简单的说就是一款让你更好的书写API文档的框架。 我们为什么选择swagger,现在的网站开发结果越来越注重前后端的分离,比如以前的webFrom到现在的mvc模式都是为了这个前后端的分离。
+关注继续查看

介绍:

Swagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案。简单的说就是一款让你更好的书写API文档的框架。

我们为什么选择swagger,现在的网站开发结果越来越注重前后端的分离,比如以前的webFrom到现在的mvc模式都是为了这个前后端的分离。就算再如何的分离实现,也是不可避免的要进行数据交互的,那么接口的重要性就提现出来了。他成了前端和后端交互的重要途径,API文档也因此成了前端开发人员与后端开发人员的重要纽带。所有我们有一个API文档框架岂不是美哉。

Swashbuckle有三个主要组件:

Swashbuckle.AspNetCore.Swagger:Swagger对象模型和中间件,将SwaggerDocument对象公开为JSON端点。
Swashbuckle.AspNetCore.SwaggerGen:一种Swagger生成器,可SwaggerDocument直接从路由,控制器和模型构建对象。它通常与Swagger端点中间件结合使用,以自动公开Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI:Swagger UI工具的嵌入式版本。它将Swagger JSON解释为构建丰富的,可定制的Web API功能描述体验。它包括用于公共方法的内置测试线束。

开始使用:

首先我们要有一个WebAPI项目,假设我们已经创建好了,不懂WebAPI如何创建的请看这篇文章:创建简单的WebAPI

好了现在我们已经有了项目那我们就开始添加引用吧:

Nuget 命令行 :Install-Package Swashbuckle.AspNetCore

添加并配置Swagger中间件:

然后配置Startup.cs 文件中的ConfigureServices方法,当然首先不要忘记引用一下using Swashbuckle.AspNetCore.Swagger命名空间,不然info类会报错。

 public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc()
                    .SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
                    .AddJsonOptions(options =>
                                    options.SerializerSettings.ContractResolver =
                                    new Newtonsoft.Json.Serialization.DefaultContractResolver());//JSON首字母小写解决;

            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = " API 文档"
                });

            });
        }

 然后在Configure方法中添加:

 //允许中间件为JSON端点服务生成的Siggg
            app.UseSwagger();
            //使中间件能够服务于轻量级用户界面(HTML、JS、CSS等),并指定SWAGJER JSON端点
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                // 要在应用程序的根处提供Swagger UI ,请将该RoutePrefix属性设置为空字符串
                c.RoutePrefix = string.Empty;
            });
View Code

启动效果:

这样就可以启动了,配置好以上就是一个最简单的api文档示例了。首先你可以访问:http://localhost:<port>/swagger/v1/swagger.json 这个网址看到端点生成的文档。

当然你想看到的是这个:http://localhost:<port>/swagger  ,你输入这个网址也可以,当然我把他配置成了根节点,这样直接启动根节点就是该页面。主要是上面代码中的: c.RoutePrefix = string.Empty这句代码。

 扩展一些显示:

我们可以扩展一些附加信息,比如作者,许可证,服务条款等。传递给该AddSwaggerGen方法的配置:

//Swagger生成器添加到方法中的服务集合中
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = " API 文档",
                    Description = "这是一个示例webapi文档",
                    //服务条款
                    TermsOfService = "None",
                    //作者信息
                    Contact = new Contact
                    {
                        Name = "ybf",
                        Email = string.Empty,
                        Url = "http://www.cnblogs.com/yanbigfeg/"
                    },
                    //许可证
                    License = new License
                    {
                        Name = "许可证名字",
                        Url = "http://www.cnblogs.com/yanbigfeg/"
                    }
                });

            });
View Code

显示结果

 xml注释:

启用XML注释可为未记录的公共类型和成员提供调试信息。未记录的类型和成员由警告消息指示。配置Swagger以使用生成的XML文件。

在我们实现前先设置一下项目属性:

 

这样就可以在项目bin下生成xml文件了。下面进行代码配置启用,还是在Startup类中的ConfigureServices方法中,在我们刚才配置的下面在增加以下代码:

 // 设置SWAGER JSON和UI的注释路径。
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                options.IncludeXmlComments(xmlPath);

使用反射主要是为了生成一个与项目文件名相同的xml文件。第二部然后是配置文件路径。这些配置好了以后。我们就可以把方法或者类的三道斜杠(“///”)的注释添加到动作。我们来看一下效果。

代码

界面:

 

 

注意哦,就是开启这个功能,项目会自动检测那些方法或者类没有注释,会给出警告。

 

取消警告小技巧:

当然我们也可以取消掉:我们在个人.csproj文件中使用分号分隔来取消警告信息:

 <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\netcoreapp2.1\SwaggerTest.xml</DocumentationFile>
    <GenerateSerializationAssemblies>On</GenerateSerializationAssemblies>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>
View Code

这样就不会有警告提示了。

描述相应类型:

接口使用者最关心的就是接口的返回内容和相应类型啦。下面展示一下201和400一个简单例子:

我们需要在我们的方法上添加:[ProducesResponseType(201)][ProducesResponseType(400)]

然后添加相应的状态说明:<response code="201">返回value字符串</response><response code="400">如果id为空</response>

最终代码应该是这个样子:

 /// <summary>
        /// values带id参数的get
        /// </summary>
        /// <param name="id">id参数</param>
        /// <returns>返回字符串类型</returns>
        /// <response code="201">返回value字符串</response>
        /// <response code="400">如果id为空</response>  
        // GET api/values/5
        [HttpGet("{id}")]
        [ProducesResponseType(201)]
        [ProducesResponseType(400)]
        public ActionResult<string> Get(int id)
        {
            return "value";
        } 
View Code

运行起来我们看一下结果:

 本例源码下载:SwaggerTest.rar

传送门:

WebApi系列文章介绍如何使用WebAPI:

WebApi系列文章目录介绍

作者:YanBigFeg —— 颜秉锋

出处:http://www.cnblogs.com/yanbigfeg

本文版权归作者和博客园共有,欢迎转载,转载请标明出处。如果您觉得本篇博文对您有所收获,觉得小弟还算用心,请点击右下角的 [推荐],谢谢!

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
Java:一个API文档框架Swagger
Java:一个API文档框架Swagger
7 0
Swagger2离线文档:PDF和Html5格式
Swagger2离线文档:PDF和Html5格式
44 0
颜值牛逼惨了的swagger-ui
颜值牛逼惨了的swagger-ui
113 0
告别swagger,加强版接口文档yapi工具安装
告别swagger,加强版接口文档yapi工具安装
58 0
Java:一个API文档框架Swagger
Java:一个API文档框架Swagger
58 0
Swagger
1.swagger介绍 现在开发,很多采用前后端分离的模式,前端只负责调用接口,进行渲染,前端和后端的唯一联系,变成了API接口。因此,API文档变得越来越重要。swagger是一个方便我们更好的编写API文档的框架,而且swagger可以模拟http请求调用。
1356 0
马斯克的挖隧道公司再下一城,未来或将首次实现短途通勤
Boring公司认为需要9到16台隧道挖掘机同时工作才能实现这一项目。
280 0
浅析如何在Nancy中使用Swagger生成API文档
原文:浅析如何在Nancy中使用Swagger生成API文档 前言 上一篇博客介绍了使用Nancy框架内部的方法来创建了一个简单到不能再简单的Document。但是还有许许多多的不足。 为了能稍微完善一下这个Document,这篇引用了当前流行的Swagger,以及另一个开源的Nancy.Swagger项目来完成今天的任务! 注:Swagger是已经相对成熟的了,但Nancy(2.0.0-clinteastwood)和Nancy.Swagger(2.2.6-alpha)是基于目前的最新版本,但目前的都是没有发布正式版,所以后续API可能会有些许变化。
1277 0
Swagger介绍-一套流行的API框架
简介   号称:世界最流行的API框架 官网:http://swagger.io/ 解决什么问题:在前后台分离的开发模式中,减小接口定义沟通成本,方便开发过程中测试,自动生成接口文档。 实例代码位置:https://github.com/pumadong/cl-roadshow/tree/master/roadshow-swagger   swagger使用方式   第一种 定义YAML文件,然后可以生成各种语言的代码框架,对于后台程序员来说,较少人会愿意写出一堆YAML格式。
1977 0
+关注
63
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
低代码开发师(初级)实战教程
立即下载
阿里巴巴DevOps 最佳实践手册
立即下载
冬季实战营第三期:MySQL数据库进阶实战
立即下载