一、为什么使用Swagger

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。

前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。

没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,有在confluence上写的,有在对应的项目目录下readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏。

书写API文档的工具有很多,但是能称之为“框架”的,估计也只有swagger了。

二、配置Swagger服务

1、建一个net Core 3.1 的API项目,不演示了都会

2、引用Nuget包

右键项目中的 依赖项 -- > 管理 Nuget 程序包 --> 浏览 --> 搜索"Swashbuckle.AspNetCore" --> Install 安装最新版

安装完成后在项目的Nuget依赖里看到刚刚引入的Swagger

3、配置服务

打开Startup.cs类,编辑ConfigureServices方法

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers(); #region swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
});
#endregion
}

3、启动Http中间件

编辑Configure方法

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
//判断是否是环境变量
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
} #region swagger
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
#endregion app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}

4、查看效果

到这,已经完成swagger的添加,F5 运行调试,在域名后面输入/swagger,例如:http://localhost:54067/swagger/index.html 点击回车,就出来了


5、设置默认直接首页访问 —— 生产环境

每次手动在域名后边输入 /swagger ,很麻烦!

swagger 给我们提供了这个扩展,我们可以指定一个空字符,作为 swagger 的地址,在Configure中配置中间件:

           #region swagger
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); c.RoutePrefix = "";//路径配置,设置为空,表示直接访问该文件,表示直接在根域名(localhost:8001)访问该文件
//这个时候去launchSettings.json中把"launchUrl": "swagger/index.html"去掉, 然后直接访问localhost:8001/index.html即可
});
#endregion

然后再把我们上边的项目文件 launchSettings.json 的 launchUrl 给去掉就行了,这样我们无论是本地开发环境,还是生产环境,都可以默认首页加载了。

这时候会发现没有注释,如果有注释可读性就很好了,下面开始实现注释

6、显示注释

1、给接口加一个注释

        /// <summary>
/// ID 获取Json列表
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpGet("{id}")]
public IEnumerable<WeatherForecast> Get(int id)

2、右键点击项目---->属性------>生成------>勾选xml文档文件

3、在startup类中的ConfigureServices 方法中的服务集合中添加如下代码

            #region swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" }); var basePath = AppContext.BaseDirectory; var xmlPath = Path.Combine(basePath, "Blog.Core.xml");
c.IncludeXmlComments(xmlPath, true); //添加控制器层注释(true表示显示控制器注释)
});
#endregion

4、运行项目并访问swaggerUI

可以显示注释了

 

7、对 Model 也添加注释说明

新建一个.net core 类库Blog.Core.Model,注意是 .net core的类库,或者使用标准库也是可以的!(标准库可以在 NetCore 和 Framework 两个项目都可以跑)

然后新建一个model

    /// <summary>
/// 这是爱
/// </summary>
public class Love
{
/// <summary>
/// id
/// </summary>
public int Id { get; set; }
/// <summary>
/// 姓名
/// </summary>
public string Name { get; set; }
/// <summary>
/// 年龄
/// </summary>
public int Age { get; set; }
}

1、当前 api 层直接引用了 Blog.Core.Model 层;

2、Blog.Core.Model 右键属性配置 xml

3、导入model.xml到swagger

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers(); #region swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" }); var basePath = AppContext.BaseDirectory; var xmlPath = Path.Combine(basePath, "Blog.Core.xml");
c.IncludeXmlComments(xmlPath, true); //添加控制器层注释(true表示显示控制器注释) var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml");
c.IncludeXmlComments(xmlModelPath, true);
});
#endregion
}

接口添加注释

        /// <summary>
/// post
/// </summary>
/// <param name="love">model 实体类</param>
[HttpPost]
public void Post(Love love)
{ }

重新运行就出来了

8、隐藏某些接口

如果不想显示某些接口,直接在controller 上,或者action 上,增加特性

[ApiExplorerSettings(IgnoreApi = true)]

        /// <summary>
/// post
/// </summary>
/// <param name="love">model 实体类</param>
[HttpPost]
[ApiExplorerSettings(IgnoreApi =true)]
public void Post(Love love)
{ }

Post方法就不显示了

三、结语

下一篇 Swagger JWT 权限,给接口加权限验证

												

Net Core3.1 添加 Swagger的更多相关文章

  1. .Net Core 分布式微服务框架 - Jimu 添加 Swagger 支持

    系列文章 .Net Core 分布式微服务框架介绍 - Jimu .Net Core 分布式微服务框架 - Jimu 添加 Swagger 支持 一.前言 最近有空就优化 Jimu (一个基于.Net ...

  2. NetCoreAPI添加Swagger

    public class Startup { public Startup(IConfiguration configuration) { Configuration = configuration; ...

  3. 如何通过注解方式给项目添加Swagger功能

    在Java后端,每次开发一个新的接口后需要自测,此时可以借助Swagger功能很好地完成自测,下面将通过注解的方式来添加Swagger. (1)代码部分 package com.bien.edge; ...

  4. (7)ASP.NET Core3.1 Ocelot Swagger

    1.前言 前端与后端的联系更多是通过API接口对接,API文档变成了前后端开发人员联系的纽带,开始变得越来越重要,而Swagger就是一款让你更好的书写规范API文档的框架.在Ocelot Swagg ...

  5. 由ASP.NET Core WebApi添加Swagger报错引发的探究

    缘起 在使用ASP.NET Core进行WebApi项目开发的时候,相信很多人都会使用Swagger作为接口文档呈现工具.相信大家也用过或者了解过Swagger,这里咱们就不过多的介绍了.本篇文章记录 ...

  6. Core3.0中Swagger使用JWT

    前言 学习ASP.NETCore,原链接 https://www.cnblogs.com/laozhang-is-phi/p/9511869.html 原教程是Core2.2,后期也升级到了Core3 ...

  7. dotnet webapi 中添加Swagger文档

    首先添加"SwaggerGenerator": "1.1.0","SwaggerUi": "1.1.0" 需要注意的是这 ...

  8. .net core 添加 Swagger

    1.新建一个Core项目 添加nuget包:Swashbuckle.AspNetCore 添加Startup文件: 先引用: using Swashbuckle.AspNetCore.Swagger; ...

  9. .Net WebApi 添加Swagger

    前言 随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染.先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远. 前端和后端的唯一联系,变成了API接口:API文档 ...

随机推荐

  1. class A<T>where T:new()是什么意思

    这是C#泛型类声明的语法class A<T> 表示 A类接受某一种类型,泛型类型为T,需要运行时传入where表明了对类型变量T的约束关系.where T:new()指明了创建T的实例时应 ...

  2. 如何安装部署和优化Tomcat?(Tomcat部署和优化与压测,虚拟主机配置,Tomcat处理请求的过程)

    文章目录 前言 一:Tomcat安装部署 1.1:Tomcat简介 1.2:Tomcat核心组件 1.3:Tomcat处理请求的过程 1.3.1:请求过程基本解释 1.3.2:请求过程详细解释 1.4 ...

  3. Python学习第十二课——json&pickle&XML模块&OS模块

    json模块 import json dic={'name':'hanhan'} i=8 s='hello' l=[11,22] data=json.dumps(dic) #json.dumps() ...

  4. LeetCode简单题(二)

    题目一: 给定一个数组 nums 和一个值 val,你需要原地移除所有数值等于 val 的元素,返回移除后数组的新长度. 不要使用额外的数组空间,你必须在原地修改输入数组并在使用 O(1) 额外空间的 ...

  5. TensorFlow样例一

    假设原函数为 f(x) = 5x^2 + 3,为了估计出这个函数,定义参数未知的函数g(x, w) = w0 x^2 + w1 x + w2,现要找出适合的w使g(x, w) ≍ f(x).将这个问题 ...

  6. centos6.9下 svn 1.7.10版本 编译安装

    svn安装推荐文章: 1.    http://blog.51cto.com/myhat/786950 2.    https://blog.csdn.net/test1280/article/det ...

  7. C++11常用特性介绍——nullptr关键字及用法

    一.nullptr关键字及用法 1)NULL的二义性 void func(int) {} void func(int*) {} 当函数调用func(NULL)时会执行哪个函数呢? 先看C++对NULL ...

  8. 阿里云服务器Ubantu16.04升级python3.6

    从ppa上下载下载python3.6 sudo apt-get install software-properties-common#使用 “add-apt-repository” 脚本添加 ppa ...

  9. Codeforces1307D. Cow and Fields

    对于本题,最短路,考虑bfs,那么我们可以跑2次bfs,求出每个点到1与n的最短路,设为x_a, x_b,那我们可以把问题转换成max(min{x_a+y_b,x_b+y_a}+1)(x,y属于1到n ...

  10. centos6.5安装图形操作界面

    yum -y install xorg-x11-fonts-Type1 #安装Xwindow yum -y groupinstall "X Window System" #安装GN ...