在ASP.NET Core Web API上使用Swagger提供API文档

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

接下来,让我们一起看一下如何在ASP.NET Core Web API上实现这一基于Swagger的API文档页面。

实现步骤

创建ASP.NET Web API应用程序

这部分内容就不多说了,方法有很多,可以在安装了Visual Studio 2015/2017 Tools for .NET Core后,使用Visual Studio 2015或者2017直接创建ASP.NET Core的应用程序,也可以使用.NET Core SDK的dotnet new –t web命令在当前文件夹下新建Web项目。本文的演示将基于Visual Studio 2015进行介绍。

添加对Swashbuckle.SwaggerUi和Swashbuckle.SwaggerGen库的引用

  1. 在Web API项目上单击鼠标右键,选择Manage NuGet Packages: 
     
     

  2. 在Visual Studio 2015 NuGet标签页中,在Browse(浏览)tab下,输入Swashbuckle.SwaggerUi,注意记得勾选“Include prerelease”选项: 
     
     

  3. 安装上图中选中的包到项目中

  4. 用上述同样的方式安装Swashbuckle.SwaggerGen包到项目中

注意:目前两个包都还是处于beta的版本,所以需要勾选Include prerelease的选项。

打开XML文档功能

  1. 在Web API项目上点击鼠标右键,选择Properties(属性)选项: 
     
     

  2. 在项目属性标签页中,切换到Build页面,同时打开XML documentation file选项: 
     
     

  3. 此时会生成Web API项目代码的XML文档。于是,编译你的项目时会产生一系列的警告信息,因为你暂时还未完成代码的文档注释

修改Startup.cs文件

  1. 双击打开Startup.cs文件

  2. 在ConfigureServices方法中,加入以下代码,以增加对Swagger的支持: 

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    public  void  ConfigureServices(IServiceCollection services)
    {
         // Add framework services.
         services.AddMvc();
         services.AddSwaggerGen();
         services.ConfigureSwaggerGen(options =>
         {
             options.SingleApiVersion( new  Swashbuckle.Swagger.Model.Info
             {
                 Version = "v1" ,
                 Title = "My Web Application" ,
                 Description = "RESTful API for My Web Application" ,
                 TermsOfService = "None"
             });
             options.IncludeXmlComments(Path.Combine(PlatformServices.Default.Application.ApplicationBasePath,
                 "WebApplication14.XML" )); // 注意:此处替换成所生成的XML documentation的文件名。
             options.DescribeAllEnumsAsStrings();
         });
    }
  3. 在Configure方法中,加入以下代码: 

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    public  void  Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
         loggerFactory.AddConsole(Configuration.GetSection( "Logging" ));
         loggerFactory.AddDebug();
         app.UseSwagger();
         app.UseSwaggerUi();
         app.UseMvc();
    }

修改Web API项目首页重定向

  1. 在项目上展开Properties节点,双击launchSettings.json文件 
     
     

  2. 根据需要,修改不同profile下的launchUrl的值,比如在本案例中,修改IIS Express节点下的launchUrl,将其改为下图中的值: 
     
     

  3. 测试一下,在Visual Studio中,将Web API项目设置成启动项,然后直接Ctrl+F5启动项目,你将看到以下画面: 
     
     

  4. 在项目中增加一些注释试试看?打开ValuesController.cs文件,增加一些注释: 
     
     

  5. 再次运行站点,发现这些文档注释都体现在API页面中了: 
     
     

  6. 我们还可以直接在API文档页面中进行API的调用测试: 

总结

本文以Walkthrough的方式介绍了如何在ASP.NET Core Web API中增加Swagger API文档页面的功能,Swagger是一个非常棒的RESTful API设计、生成、文档化以及规范化工具,它基于YAML语言,并在官方提供了YAML语言的编辑器。开发人员可以通过各种编辑器,用YAML定义RESTful API的接口契约,同时还可以生成几十种编程语言的RESTful服务端和客户端代码(在上面的截图中,大家有没有留意到绿色背景标题栏中的swagger.json文件URL?下载这个文件,然后到官网的编辑器中导入后,即可立刻根据自己的开发语言,下载包含有我们的RESTful API实现的服务端框架和客户端调用代码)。这有点像SOAP Web Services时代的WSDL(Web Service描述语言)以及wsdl.exe、svcutil.exe等工具。除了Swagger,RAML也是一种同类产品,有兴趣的朋友可以去它们各自的官网了解

原文地址:http://www.cnblogs.com/daxnet/p/6181366.html


.NET社区新闻,深度好文,微信中搜索dotNET跨平台或扫描二维码关注

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/327088.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

一文告诉你 Java RMI 和 RPC 的区别

转载自 一文告诉你 Java RMI 和 RPC 的区别 RPC 远程过程调用 RPC(Remote Procedure Call Protocol)远程过程调用协议,通过网络从远程计算机上请求调用某种服务。一次RPC调用的过程大概有10步: 1.执行客户端调用语句&#xff…

java实现人脸识别源码【含测试效果图】——Dao层(IBaseDaoUtil)

/*** */ package org.dao;/*** * * 项目名称:test_face_photo * 类名称:IBaseDaoUtil * 类描述: 共用接口 * 创建人:Mu Xiongxiong * 创建时间:2017-9-22 下午6:59:36 * 修改人:Mu Xiong…

stream 提取某字段_java8从list集合中取出某一属性的值的集合案例

List orderNoListlist.stream().map(Order::getOrderNo).collect(Collectors.toList()); https://blog.csdn.net/weixin_39702400/article/details/111895006 我就废话不多说了,大家还是直接看代码吧~ List list new ArrayList(); Order o1 new Order("1&q…

线程VS进程

什么是线程、什么是进程 在Java中要同时执行(如果是单核,准确的说是交替执行)多个任务,使用的是多线程,而要理解线程,我们先要了解什么是进程什么是线程。 一般的定义:进程是指在操作系统中正在…

Java架构师必须知道的 6 大设计原则

转载自 Java架构师必须知道的 6 大设计原则 在软件开发中,前人对软件系统的设计和开发总结了一些原则和模式, 不管用什么语言做开发,都将对我们系统设计和开发提供指导意义。本文主要将总结这些常见的原则,和具体阐述意义。 开发…

java实现人脸识别源码【含测试效果图】——Dao层(IUserDao)

/** * Title: IUserDao.java * Package org.dao * Description: TODO该方法的主要作用: * author A18ccms A18ccms_gmail_com * date 2017-9-22 下午8:51:34 * version V1.0 */ package org.dao;import org.entity.Users;/** * * 项目名称:te…

Flux --gt; Redux --gt; Redux React 入门 基础实例教程

本文的目的很简单,介绍Redux相关概念用法 及其在React项目中的基本使用 假设你会一些ES6、会一些React、有看过Redux相关的文章,这篇入门小文应该能帮助你理一下相关的知识 一般来说,推荐使用 ES6ReactWebpack 的开发模式,但Webpa…

mybatisplus 强制制空 空覆盖原来的字符串

ApiModelProperty(value "证件照片url") TableField(value "id_photo_url",fill FieldFill.UPDATE) private String idPhotoUrl; 方法一 Data EqualsAndHashCode(callSuper false) Accessors(chain true) TableName("base_party_member") A…

Callable和Future

它们俩其实挺有意思,在运行的时候各司其职,Callable产生结果,Future获取结果。 使用步骤如下: 创建 Callable 接口的实现类,并实现 call() 方法,该 call() 方法将作为线程执行体,并且有返回值…

java实现人脸识别源码【含测试效果图】——DaoImpl层(BaseDaoUtilImpl)

/*** */ package org.dao.impl;import java.sql.ResultSet; import java.sql.SQLException; import java.util.ArrayList; import java.util.List;import org.dao.BaseDao; import org.entity.Users; import org.junit.Test;/*** * * 项目名称:test_BaseDao …

90 % Java 程序员被误导的一个性能优化策略

转载自 90 % Java 程序员被误导的一个性能优化策略 我们经常看到一些 Java 性能优化的书或者理念,说不要在循环内定义变量,这样会占用过多的内存影响性能,而要在循环外面定义。接触 Java 这么久以来,相信很多 Java 程序员都被这…

微软开源Visual Studio测试平台VSTest

IT之家1月21日消息 微软在MSDN博客上宣布,开源旗下Visual Studio测试平台VSTest。这一平台是具备高扩展性的单元测试执行框架,能够在不同的核心之间实现并行化,提供进程隔离,并能够整合进Visual Studio。 目前,VSTest能…

nacos 读取纯数字字符 出错 @value

ums: baseUrl: http://xxxx/xx/Api code: 00972315 纯数字要加单引号

java实现人脸识别源码【含测试效果图】——DaoImpl层(UserDaoImpl)

/** * Title: UserDaoImpl.java * Package org.dao.impl * Description: TODO该方法的主要作用: * author A18ccms A18ccms_gmail_com * date 2017-9-22 下午8:52:58 * version V1.0 */ package org.dao.impl;import org.dao.IUserDao; import org.entity.Use…

线程的状态与调度

当我们使用new关键字新建一个线程,这个时候线程就进入了新建状态(New),也就是图中未启动状态;调用start方法启动线程,这个时候就进入了可运行状态,也就是就绪状态(Runnable&#xff…

深入JVM系列(三)之类加载、类加载器、双亲委派机制与常见问题

转载自 深入JVM系列(三)之类加载、类加载器、双亲委派机制与常见问题 一.概述 定义:虚拟机把描述类的数据从Class文件加载到内存,并对数据进行校验、转换解析和初始化,最终形成可以被虚拟机直接使用的java…

Fabio 安装和简单使用

Fabio(Go 语言):https://github.com/eBay/fabio Fabio 是一个快速、现代、zero-conf 负载均衡 HTTP(S) 路由器,用于部署 Consul 管理的微服务。 Fabio 由 eBay Classifieds Group 开发,用于处理 marktplaats.nl 和 kij…

java实现人脸识别源码【含测试效果图】——Service层(IUserService)

/** * Title: BaseService.java * Package org.service * Description: TODO该方法的主要作用: * author A18ccms A18ccms_gmail_com * date 2017-9-22 下午8:48:52 * version V1.0 */ package org.service;import org.entity.Users;/** * * 项目名称&am…

join()

join函数的定义是指:等待线程终止。 我们在运行线程的时候可能会遇到,在主线程中运行子线程,主线程需要获取子线程最终执行结果的情况。 但是有很多时候子线程进行了很多耗时的操作,主线程往往先于子线程结束,这个时…

计算密集型分布式内存存储和运算平台架构

1. 相关概念 1.1 内存数据库 关系型数据库处理永久、稳定的数据,内存数据库就是将其数据放在内存中,活动事务只与内存数据打交道,重新设计了体系结构并且在数据缓存、快速算法、并行操作方面也进行了相应的改进,所以数据处理速度比…