对于开发人员来说,构建一个消费应用程序时去了解各种各样的 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. 使用Sphinx为你的python模块自动生成文档

    Sphinx是一个可以用于Python的自动文档生成工具,可以自动的把docstring转换为文档,并支持多种输出格式包括html,latex,pdf等. 安装 创建一个sphinx项目 下面的命令会 ...

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

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

  4. 使用swagger在netcorewebapi项目中自动生成文档

    一.背景 随着前后端分离模式大行其道,我们需要将后端接口撰写成文档提供给前端,前端可以查看我们的接口,并测试,提高我们的开发效率,减少无效的沟通.在此情况下,通过代码自动生成文档,这种需求应运而生,s ...

  5. MVC WEB api 自动生成文档

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

  6. swagger生成文档初步使用

    在大部分情况下,公司都会要求提供详细的接口文档,对于开发来说,文档有时候在赶进度的情况下,也是一件头疼的事.而swagger的自动生成文档功能,就可以帮助我们减少工作量,对于文档的修改也可以在代码中随 ...

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

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

  8. 用doxygen自动生成文档

    1. 添加符合doxygen解析规则的注释 (比如函数说明,函数参数/返回值说明) 用qt-creator可以在函数上方一行键入“/**”,然后直接回车,就可以自动生成默认的格式. 2. 安装doxy ...

  9. linux c/c++ 代码使用 doxygen 自动生成文档

    www.doxygen.org 的使用非常方便,下面分成2步介绍一下 1. 注释风格,需要在c/c++代码中按照下面的风格添加注释,基本上还是很顺手的 C++的注释风格 主要使用下面这种样式:即在注释 ...

随机推荐

  1. 转:关于BFC的初步了解以及常见使用

    在学习CSS的过程中,掌握一些常用方法或效果实现的原理对于我们的学习来说是很有帮助的.如最常见的清除浮动和取消外边距塌陷时使用overflow:hidden;,在学习初期往往只知道有这种用法,且使用时 ...

  2. ajax 之js读取xml的多浏览器兼容

    主要是分为两大类:IE.其它浏览器 IE8以下只支持这种 InputVoltage.innerText = xmlDoc.getElementsByTagName(id)[0].text, 其它浏览器 ...

  3. hdu 5188

    it's a  dp  difficult problem 试想如果我们遇见这样一道题,: 有n道题目,每道题有一个得分v和用时t: 我们要得够w分:用时最少  怎么做?? 这是一个裸奔的01背包 如 ...

  4. 【CF 675D Tree Construction】BST

    题目链接:http://codeforces.com/problemset/problem/675/D 题意:给一个由n个互异整数组成的序列a[],模拟BST的插入过程,依次输出每插入一个元素a[i] ...

  5. 一张地图,告诉你NodeJS命令行调试器语句

    NodeJS提供脚本调试. 进入node debug xx.js您可以进入调试模式. 版权声明:本文博客原创文章,博客,未经同意,不得转载.

  6. 配置IIS使用Python

    打开IIS管理器 选择功能视图,然后选择ISAPI和CGI限制 打开后,在右侧操作,点击添加,会出现下图所示 按图中提示填写相应部分,在选择路径时,默认可能是dll文件,改成全部文件即可,然后再选择p ...

  7. C#设计模式之1:策略模式

    首先需要说明的是该系列的所有内容都是基于headfirst设计模式来描述的.因为我之前也看过不少关于设计模式的书,还是发现这本最好,因为这本书里面给出的例子是最贴切实际的.不说了,开始这个系列吧! 策 ...

  8. PYTHON-操作系统基础

    预习:操作系统基础1,编程语言的分类2,多版本共存3,执行python程序的两种方式4,变量5,输入输出6,运算符7,基本数据类型8,流程控制之if ------------------------- ...

  9. CF161D Distance in Tree(点分治)

    点分治是一种处理树的优秀暴力 这是一道板子题 #include <cstdio> #include <cstring> #include <algorithm> u ...

  10. mac下配置android开发环境

    从昨天下午到如今.用了差点儿相同一整天的时间去熟悉mac和配置环境,基本已经OK了,大体记录了整个过程中遇到的问题. 1.安装java环境 之前听说mac自带java环境.java -version一 ...