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

Swashbuckle 有两个核心的组件
Swashbuckle.SwaggerGen : 提供生成描述对象、方法、返回类型等的 JSON Swagger 文档的功能。
Swashbuckle.SwaggerUI : 是一个嵌入式版本的 Swagger UI 工具,使用 Swagger UI 强大的富文本表现形式来可定制化的来描述 Web API 的功能,并且包含内置的公共方法测试工具。

新建一个ASP.NET Core WebApi 项目,项目结构如下图所示:

使用NUget进行添加Swashbuckle

1、工具->NUget包管理器->程序包管理器控制台

2、在控制台输入: Install-Package Swashbuckle -Pre  按下回车键

3、安装Swashbuckle完成:

4、安装Swashbuckle完成后台项目的引用发生了变化:

5、在 project.json 中添加多了一项配置 "Swashbuckle": "6.0.0-beta902" :

7、启用 XML 注释, 在 Visual Studio 中右击项目并且选择 Properties 在 Output Settings 区域下面点击 XML Documentation file 。

9、在 project.json 中设置 “xmlDoc”: true 来启用 XML 注释。

10、在Startup.cs类的 ConfigureServices 方法中,允许中间件提供和服务生成 JSON 文档以及 SwaggerUI。Configure 方法中把 SwaggerGen 添加到 services 集合。配置 Swagger 使用生成的 XML 文件

 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.PlatformAbstractions;
 using Swashbuckle.Swagger.Model;

 namespace dotNetCore_Test1
 {

     public class Startup
     {
         public Startup(IHostingEnvironment env)
         {
             var builder = new ConfigurationBuilder()
                 .SetBasePath(env.ContentRootPath)
                 .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                 .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);

             if (env.IsEnvironment("Development"))
             {
                 // This will push telemetry data through Application Insights pipeline faster, allowing you to view results immediately.
                 builder.AddApplicationInsightsSettings(developerMode: true);
             }
             builder.AddEnvironmentVariables();
             Configuration = builder.Build();
         }

         public IConfigurationRoot Configuration { get; }

         // This method gets called by the runtime. Use this method to add services to the container
         public void ConfigureServices(IServiceCollection services)
         {
             // Add framework services.
             services.AddApplicationInsightsTelemetry(Configuration);

             services.AddMvc();

             //services.AddLogging();

             // 注入的实现ISwaggerProvider使用默认设置
             services.AddSwaggerGen();

             services.ConfigureSwaggerGen(options =>
             {
                 options.SingleApiVersion(new Info
                 {
                     Version = "v1",
                     Title = "测试ASP.NET Core WebAPI生成文档(文档说明)",
                     Description = "A simple example ASP.NET Core Web API",
                     TermsOfService = "None",
                     Contact = new Contact { Name = "linyongjie", Email = "", Url = "https://docs.microsoft.com/zh-cn/aspnet/core/" },
                     License = new License { Name = "Swagger官网", Url = "http://swagger.io/" }
                 });

                 var basePath = Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationBasePath; // 获取到应用程序的根路径
                 options.IncludeXmlComments(basePath + "\\dotNetCore_Test1.xml");  //是需要设置 XML 注释文件的完整路径
             });

         }

         // This method gets called by the runtime. Use this method to configure the HTTP request pipeline
         public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
         {
             loggerFactory.AddConsole(Configuration.GetSection("Logging"));
             loggerFactory.AddDebug();

             app.UseApplicationInsightsRequestTelemetry();

             app.UseApplicationInsightsExceptionTelemetry();

             app.UseMvc();

             app.UseSwagger(); //使中间件服务生成Swagger作为JSON端点

             app.UseSwaggerUi();  //使中间件服务swagger-ui assets (HTML、javascript、CSS等等)

         }
     }
 }

11、新建一个User(用户)Model用于测试:

 using System;
 using System.Collections.Generic;
 using System.ComponentModel.DataAnnotations;
 using System.Linq;
 using System.Threading.Tasks;

 namespace dotNetCore_Test1.Models
 {

     /// <summary>
     /// 用户模型
     /// </summary>
     public class User
     {

         /// <summary>
         /// 年龄
         /// </summary>
         public int Age { set; get; }

         /// <summary>
         /// 名称
         /// </summary>
         [Required]  //此配置可以约束(Swagger )传进来的参数值 不能为空
         public string Name { get; set; }

         /// <summary>
         /// 性别
         /// </summary>
         public string Sex { get; set; }
     }
 }

12、添加了XML注释控制器例子:

 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Mvc;

 namespace dotNetCore_Test1.Controllers
 {
     /// <summary>
     /// 测试 Swagger的 XML 注释
     /// </summary>
     [Route("api/[controller]")]
     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>
         [HttpGet("{id}")]
         public string Get(int id)
         {
             return "value";
         }

         /// <summary>
         /// 添加一个用户
         /// </summary>
         /// <remarks>
         ///
         ///     POST /User
         ///     {
         ///        "Age": "年龄",
         ///        "Name": "名称",
         ///        "Sex": "性别
         ///     }
         ///
         /// </remarks>
         /// <param name="item">用户的json对象</param>
         /// <returns>返回一个对象</returns>
         /// <response code="201">返回新创建的项目</response>
         /// <response code="400">如果item是null</response>
         [HttpPost]
         [ProducesResponseType()]
         [ProducesResponseType()]
         [HttpPost]
         public IActionResult Post([FromBody]dotNetCore_Test1.Models.User item)
         {
             if (item == null)
             {
                 return BadRequest();
             }
             return Ok(item);
         }

         /// <summary>
         /// 删除一个对象
         /// </summary>
         /// <remarks>
         /// 这里可以写详细的备注
         /// </remarks>
         /// <param name="id">主键id标识</param>
         [HttpDelete("{id}")]
         public void Delete(int id)
         {
         }
     }
 }

13、通过访问 http://localhost:<random_port>/swagger/ui 查看Swagger 自动生成文档 (<random_port> 表示IIS Express随机分配的端口号,我测试的demo分配的端口号是:51109,所以我这里查看Swagger生成的文档地址是http://localhost:51109/swagger/ui/index.html#/Values)生成的文档如下图:

13.1、

13.2

13.3

13.4

配置 Swagger 使用生成的 XML 文件

使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)的更多相关文章

  1. xcode 自动添加注释,生成文档

    一.自动生成注释代码        添加一个快捷键,生成 注释代码        ThisService 下载连接:http://wafflesoftware.net/thisservice/     ...

  2. ASP.NET Core 1.0 中使用 Swagger 生成文档

    github:https://github.com/domaindrivendev/Ahoy 之前文章有介绍在ASP.NET WebAPI 中使用Swagger生成文档,ASP.NET Core 1. ...

  3. MVC WEB api 自动生成文档

    最近在一直在用webapi做接口给移动端用.但是让我纠结的时候每次新加接口或者改动接口的时候,就需要重新修改文档这让我很是苦恼.无意中发现.webapi居然有自动生成文档的功能....真是看见了救星啊 ...

  4. eoLinker 新功能发布,增加了识别代码注释自动生成文档功能

    产品地址:https://www.eolinker.com开源代码:https://www.eolinker.com/#/os/download在线生成代码注释工具:http://tool.eolin ...

  5. ASP.NET Core 中文文档 第二章 指南 (09) 使用 Swagger 生成 ASP.NET Web API 在线帮助测试文档

    原文:ASP.NET Web API Help Pages using Swagger 作者:Shayne Boyer 翻译:谢炀(kiler) 翻译:许登洋(Seay) 对于开发人员来说,构建一个消 ...

  6. ASP.NET Web API 使用Swagger生成在线帮助测试文档

    Swagger-UI简单而一目了然.它能够纯碎的基于html+javascript实现,只要稍微整合一下便能成为方便的API在线测试工具.项目的设计架构中一直提倡使用TDD(测试驱动)原则来开发,sw ...

  7. 1.0 添加WEB API项目并按注释生成文档(多项目结构)

    1.新建ASP.NET 项目,模板选择如图 2.选择Web API,并选择不进行身份验证方式 成功后我们看到这个结果. 至于其它三种身份验证方式,不太适合我的使用.而且这种方式也可以在代码里去实现身份 ...

  8. 前端那点事儿——Tocify自动生成文档目录

    今天偶然间看到文档服务器有一个动态目录功能,点击目录能跳转到指定的位置:窗口滑动也能自动更新目录的焦点. 效果 框架 原来使用的是一个开源的jquery-ui控件——tocify.js,它可以遍历页面 ...

  9. Eclipse自动生成文档注释

    /** *这种格式的注释就是文档注释 */ 快捷键是alt+shift+j,将光标放在类名,变量名,方法名上,按快捷键.

随机推荐

  1. [Oracle]快速插入大量(100w)数据

    背景:无论在开发调试或者软件测试中,测试数据的准备是调试/测试执行前重要和必要的一个环节,因此以下几种方式可以快速插入大量数据: 第一种方法: declare   -- Local variables ...

  2. UnityContainer 实现DI

    DI(依赖注入) 的方式有很多种: 接口注入,属性注入,构造注入等.DI主要是为了实现代码的松耦合,方便代码的维护和扩展.(其实都是扯淡). 来说说我为啥要使用DI吧.公司有个项目,需要我一个人完成( ...

  3. 关于Kean博客的学习

    由于我从事设计行业,使用Autocad进行绘图是一件单调但是拥有乐趣的工作. 大约在一年前,接触到了CAD的二次开发的内容,它使我感到新奇,并且决定花时间来研究相关的知识.这时我在网上浏览到了Kean ...

  4. Deep learning:四十七(Stochastic Pooling简单理解)

    CNN中卷积完后有个步骤叫pooling, 在ICLR2013上,作者Zeiler提出了另一种pooling手段(最常见的就是mean-pooling和max-pooling),叫stochastic ...

  5. HtmlAgilityPack 删除script、style以及注释标签

    foreach(var script in doc.DocumentNode.Descendants("script").ToArray()) script.Remove(); f ...

  6. 如何在Eclipse卸载之前添加的android 的 ADT

    Android开发环境配置中,怎么卸载ADT? 在Android开发环境配置中,可能会遇到很多问题,其中ADT安装失败需要卸载,怎么卸载呢?下面讲一种方法,希望能够对你有所帮助. 我采用的是Eclip ...

  7. java 15-1 Collection集合的概述以及小功能介绍

     集合的由来:  我们学习的是面向对象语言,而面向对象语言对事物的描述是通过对象体现的,为了方便对多个对象进行操作,我们就必须把这多个对象进行存储.  而要想存储多个对象,就不能是一个基本的变量,而应 ...

  8. Apache VirtualHost配置

    转载:http://www.cnblogs.com/wpjsolo/archive/2012/01/19/2327457.html 以lampp环境为例子,其他环境只是配置文件的路径不同. 先要在   ...

  9. [系统开发] Squid 认证系统

    一.用途 用过 Squid 的用户认证模块的同事一定知道,它有个很麻烦的问题:每过一段时间就会跳出一个重新输入密码的窗口,用户不胜其烦,我查了网上的各种配置资料,始终没有找到一个圆满的解决方法,所以编 ...

  10. java 构造函数内部的多态方法 完全剖析

    我们先来看一个例子,如果你读过<java编程思想>的话 应该会有印象 package com.test.zj; public class PolyConstructors { public ...