⒈新建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. axios 的坑

    必须安装axios 和qs 1.main.js中的配置 import axios from 'axios' import qs from 'qs'; axios.defaults.headers.po ...

  2. [题解] [CF451E] Devu and Flowers

    题面 题解 就是一个求\(\sum_{i= 1}^{n}x _ i = m\)的不重复多重集的个数, 我们可以由容斥原理得到: \[ ans = C_{n + m - 1}^{n - 1} - \su ...

  3. 三、Reids(高性能)key-value服务器知识整合

    一.Redis 是完全开源免费的,遵守BSD协议,是一个高性能的key-value数据库. 知识链接:https://www.runoob.com/redis/redis-backup.html ht ...

  4. Nginx事件管理之ngx_event_core_module模块

    1. 概述 ngx_event_core_module 模块是一个事件类型的模块,它在所有事件模块中的顺序是第一位.它主要完成以下两点任务: 创建连接池(包括读/写事件): 决定究竟使用哪些事件驱动机 ...

  5. spring-jms,spring-boot-starter-activemq JmsTemplate 发送方式

    spring-jms,spring-boot-starter-activemq JmsTemplate 发送方式 背景: 原来我准备是setDefaultDestinationName 设置队列的名称 ...

  6. MapInfo 文件解析

    在MapInfo 中所指的表是单纯的数据表或是图形与数据的结合.一个典型的MapInfo表将主要由*.tab.*.dat.*.wks.*.dbf. *.xls.*.map.*.id.*.ind文件格式 ...

  7. 云服务器 ECS 是什么?

    云服务器 Elastic Compute Service(ECS)是阿里云提供的一种基础云计算服务.使用云服务器 ECS 就像使用水.电.煤气等资源一样便捷.高效.您无需提前采购硬件设备,而是根据业务 ...

  8. [go]beego获取参数/返回参数

    获取前端传来的参数 获取数据并转为对应的类型 - ?id=111&id=122 c.GetInt("id") int,111 - ?id=111&id=122 c. ...

  9. linux系统交互通道

    默认有6个命令交互通道和一个图形界面交互通道,默认进入到的是图形界面通道     命令交互模式切换:ctrl+alt+f1---f6     图形交互界面 ctrl+alt+f7 1.图形界面交互模式 ...

  10. DownloadManager系统自带下载实现apk后台下载功能

    DownloadManager是android2.3以后,系统下载的方法,是处理长期运行的HTTP下载的系统服务.客户端可以请求的URI被下载到一个特定的目标文件.客户端将会在后台与http交互进行下 ...