⒈新建ASP.NET Core WebAPi项目

⒉添加 NuGet 包

Install-Package Swashbuckle.AspNetCore

⒊Startup中配置

 using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using Swashbuckle.AspNetCore.Swagger; namespace SwaggerXmlDemo
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
} public IConfiguration Configuration { get; } // 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); //注册Swagger生成器,定义一个和多个Swagger 文档
services.AddSwaggerGen(option =>
{
//配置第一个Doc
option.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "My API_1",
Description = "Document Api",
Contact = new Contact
{
Name = "fanqi",
Email = "fanqisoft@163.com",
Url = "https://www.coreqi.cn"
}
});
});
} // 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();
} //启用中间件服务生成Swagger作为JSON终结点
app.UseSwagger(); //启用中间件服务对swagger-ui,指定Swagger JSON终结点
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "DemoAPI V1");
//c.RoutePrefix = "swagger"; //默认
c.RoutePrefix = string.Empty;
}); app.UseMvc();
}
}
}

⒋添加注释信息

 using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks; namespace SwaggerXmlDemo.Models
{
/// <summary>
/// 用户实体类
/// </summary>
public class User
{
/// <summary>
/// 用户主键Id
/// </summary>
/// <example></example>
public int id { get; set; }
/// <summary>
/// 用户名
/// </summary>
/// <example>fanqi</example>
public string username { get; set; }
/// <summary>
/// 用户密码
/// </summary>
/// <example>admin</example>
public string password { get; set; }
/// <summary>
/// 用户年龄
/// </summary>
/// <example></example>
public int? age { get; set; }
/// <summary>
/// 用户邮箱
/// </summary>
/// <example>fanqisoft@163.com</example>
public string email { get; set; }
}
}
 using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using SwaggerXmlDemo.Models; namespace SwaggerDemo.Controllers
{
/// <summary>
/// 用户Api控制器
/// </summary>
[Route("api/[controller]")]
[ApiController]
public class UserController : ControllerBase
{
/// <summary>
/// 获取系统用户列表
/// </summary>
/// <remarks>
/// Demo
/// Get /api/user/get
/// </remarks>
/// <returns>系统用户列表</returns>
/// <response code="201">返回用户列表</response>
/// <response code="401">没有权限</response>
[HttpGet("get")]
[ProducesResponseType()]
[ProducesResponseType()]
public IList<User> GetUsers()
{
return new List<User>
{
new User{ id = ,username = "fanqi",password = "admin",age = ,email = "fanqisoft@163.com"},
new User{ id = ,username = "gaoxing",password = "admin",age = ,email = "gaoxing@163.com"}
};
} /// <summary>
/// 新建用户
/// </summary>
/// <param name="user">新建用户信息</param>
/// <returns>是否创建成功信息</returns>
[HttpPost("add")]
public IActionResult CreateUser([FromForm] User user)
{
return Ok();
}
}
}

⒋启用XML注释

  1.右键单击“解决方案资源管理器”中的项目,然后选择“属性”

  2.勾选“生成”选项卡“输出”部分的“XML 文档文件”框

右键生成的XML文件,选择属性。修改“复制到输出目录”为“始终复制”。

启用 XML 注释后会为未记录的公共类型和成员提供调试信息将会出现很多CS1591警告信息。直接无视即可。

警告   CS1591	缺少对公共可见类型或成员“xxxxx”的 XML 注释 指定了 /doc 编译器选项,但是一个或多个构造没有注释。

如果有强迫症,可以按照下图所示进行取消

注意上面生成的xml文档文件的路径,

注意:

​ 1.对于 Linux 或非 Windows 操作系统,文件名和路径区分大小写。 例如,“SwaggerDemo.xml”文件在 Windows 上有效,但在 CentOS 上无效。

​ 2.获取应用程序路径,建议采用Path.GetDirectoryName(typeof(Program).Assembly.Location)这种方式或者·AppContext.BaseDirectory这样来获取

⒌为 Swagger JSON和UI设置xml文档注释路径

         // 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); //注册Swagger生成器,定义一个和多个Swagger 文档
services.AddSwaggerGen(option =>
{
//配置第一个Doc
option.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "My API_1",
Description = "Document Api",
Contact = new Contact
{
Name = "fanqi",
Email = "fanqisoft@163.com",
Url = "https://www.coreqi.cn"
}
}); // 为 Swagger JSON and UI设置xml文档注释路径
//var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录(绝对,不受工作目录影响,建议采用此方法获取路径)
//var xmlPath = Path.Combine(basePath, "SwaggerXmlDemo.xml");
var filePath = Path.Combine(System.AppContext.BaseDirectory, "SwaggerXmlDemo.xml");
option.IncludeXmlComments(filePath);
});
}

⒍查看效果

ASP.NET Core WebApi使用Swagger生成API说明文档【xml注释版】的更多相关文章

  1. ASP.NET Core WebApi使用Swagger生成API说明文档【特性版】

    ⒈新建ASP.NET Core WebAPi项目 ⒉添加 NuGet 包 Install-Package Swashbuckle.AspNetCore ⒊Startup中配置 using System ...

  2. ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

    引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...

  3. ASP.NET Core WebApi使用Swagger生成api说明文档

    1. Swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件 ...

  4. 【转】ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

    原文链接:https://www.cnblogs.com/yilezhu/p/9241261.html 引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必 ...

  5. 三分钟学会 ASP.NET Core WebApi使用Swagger生成api说明文档

    什么是Swagger?为啥要用Swagger? Swagger可以从不同的代码中,根据注释生成API信息,Swagger拥有强大的社区,并且对于各种语言都支持良好,有很多的工具可以通过swagger生 ...

  6. ASP.NET Core WebApi使用Swagger生成api

    引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...

  7. ASP.NET WebApi使用Swagger生成api说明文档

    最近做的项目使用mvc+webapi(非.Net Core),采取前后端分离的方式,后台提供API接口给前端开发人员.这个过程中遇到一个问题后台开发人员怎么提供接口说明文档给前端开发人员,最初打算使用 ...

  8. Asp.Net Core下使用swagger生成api文档

    目录 一.前期准备 二.配置Swagger 三.参考 .Net Core中有两个集成NSwag的包,分别为Swashbuckle和NSwag.两者的配置大同小异.这里以NSwag为例. 一.前期准备 ...

  9. NetCore 3.0 中使用Swagger生成Api说明文档及升级报错原因

    认识Swagger Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参 ...

随机推荐

  1. 20190716NOIP模拟赛T1 礼物(概率dp+状压)

    题目描述 夏川的生日就要到了.作为夏川形式上的男朋友,季堂打算给夏川买一些生 日礼物. 商店里一共有种礼物.夏川每得到一种礼物,就会获得相应喜悦值Wi(每种 礼物的喜悦值不能重复获得). 每次,店员会 ...

  2. Jmeter -- 脚本录制

    步骤如下: 1. 添加http代理服务器(Add -> Non-TestElement -> HTTP(S)Test Script Recorder) 2. 对http代理进行配置,如下图 ...

  3. brute爆破

    0X01明文传输的表单爆破用户名和密码 不存在任何加密 直接爆破即可 当不存在用户名时: 当存在用户名时,密码错误: 这里由于靶场关了 所以我们用dvwa演示 但是dvwa没有以上的差别 所以我们默认 ...

  4. UEFI和GPT

    好就没用linux了,这几天在win8笔记本上用虚拟机装了下,也准备装到硬盘上和win8双系统使用,发现一些概念已经跟不上时代了. 一个是在虚拟机中装的时候,分配了虚拟硬盘分区时,提示选择分区表类型, ...

  5. word 之 插入删除空行

    好久没有写程序了.有些手生: 在用C#对word进行直接开发操作过程中,为了文档的美观,我们会插入或删除空行. 1.插入空行的代码很简单. Selection 类型的TypeParagraph()函数 ...

  6. oracle性能诊断sql

    --1.阻塞及等待事件信息查询-- 查询所有会话的状态.等待类型及当前正在执行的SQL脚本select t.SID, t.SERIAL#, t.Status, t.Action, t.Event, t ...

  7. tensorflow dnn 参考

    https://blog.csdn.net/qq_35976351/article/details/80793487

  8. Hibernate HelloWorld案例

    搭建一个Hibernate环境,开发步骤: 1. 下载源码 版本:hibernate-distribution-3.6.0.Final 2. 引入jar文件          hibernate3.j ...

  9. [zookeeper]依赖jar的问题

    zookeeper是依赖以下三个jar包 log4j-1.2.17.jar slf4j-api-1.7.25.jar slf4j-log4j12-1.7.18.jar 否则会报异常:java.lang ...

  10. 六十四:CSRF攻击与防御之系统准备之病毒网站转账实现

    准备一个页面或图片,用于用户访问 一:表单方式 视图 from flask import Flask, render_template app = Flask(__name__) @app.route ...