一、安装swagger

  新建一个net core的api项目,通过NuGet安装Swashbuckle.AspNetCore。

二、注册swagger服务

  在Startup.cs中注册Swagger生成器。

        public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
//注册Swagger生成器,定义一个和多个Swagger 文档
#region Swagger
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
#endregion
}

  启用Swagger。

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseHsts();
} #region Swagger
//启用中间件服务生成Swagger作为JSON终结点
app.UseSwagger();
//启用中间件服务对swagger-ui,指定Swagger JSON终结点
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
#endregion app.UseHttpsRedirection();
app.UseMvc();
}

  控制器如下。

    [Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
public ActionResult<string> Get()
{
return "value";
}
[HttpPost]
public void Post([FromBody] string value)
{
}
[HttpPut("{id}")]
public void Put(int id, [FromBody] string value)
{
}
[HttpDelete("{id}")]
public void Delete(int id)
{
}
}

  启动项目,访问路径/swagger,就可以看到文档内容了,但是我们可以发现报错如下。

  访问路径/swagger/v1/swagger.json可以发现,swagger需要显示绑定http方法,由于第一个get方法没有绑定所以报错了,解决方法有两个:

  1、显示绑定http方法,如添加特性[HttpGet]等。

  2、添加特性[ApiExplorerSettings(IgnoreApi = true)],让swagger忽略这个接口。

三、文档的描述

  1、接口描述

  首先需要设置文档的输出路径,进入项目的属性->生成,设置输出路径如下

  然后在Startup.cs->ConfigureServices方法中设置输出路径

            services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
// 设置SWAGER JSON和UI的注释路径。
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments(xmlPath);
});

  对于接口的注释和我们平常的注释一样。

        /// <summary>
/// 提交数据
/// </summary>
/// <remarks>
/// 备注:返回数据。。。
/// </remarks>
/// <param name="value">值</param>
/// <response code="200">返回成功</response>
/// <response code="500">返回失败</response>
[HttpPost]
public void Post([FromBody] string value)
{
}

  对于没有注释的方法会报警告,如果不喜欢就可以在项目的属性->生成中设置隐藏

  2、版本的描述

  对于接口,随着版本的迭代会有很多的版本,所以通过版本的描述可以更简单的找到对应的接口。对于swagger可以添加多个文档的描述并且设置多个终结点显示不同版本的接口文档。

        public void ConfigureServices(IServiceCollection services)
{
//注册Swagger生成器,定义一个和多个Swagger 文档
#region Swagger
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1", Contact = new Contact { Name = "小小开发者", Email = " think@mr_lv" } });
options.SwaggerDoc("v2", new Info { Title = "My API", Version = "v2", Contact = new Contact { Name = "小小开发者", Email = " think@mr_lv" } });
});
#endregion
}
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
#region Swagger
//启用中间件服务生成Swagger作为JSON终结点
app.UseSwagger();
//启用中间件服务对swagger-ui,指定Swagger JSON终结点
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
options.SwaggerEndpoint("/swagger/v2/swagger.json", "v2");
});
#endregion
}

  这里要特别注意不同的版本名称对应不同的终结点。不对应会导致一直只有一种的尴尬。当然我们的接口也需要设置属于那个版本通过特性[ApiExplorerSettings(GroupName = "v1")]。如果不设置那这任何版本中都会出现。效果如下:

四、swagger其他补充

  1、swagger支持token授权认证

  2、swagger生成离线文档

  3、swagger接口多版本控制补充

Net Core的API文档工具Swagger的更多相关文章

  1. API文档工具-Swagger的集成

    最近安装了API文档工具swagger,因为Github上已有详细安装教程,且安装过程中没有碰到大的阻碍,所以此文仅对这次安装做一份大致记录 相关网站 Swagger 官方地址: http://swa ...

  2. .Net Core3.0 WebApi 项目框架搭建 二:API 文档神器 Swagger

    .Net Core3.0 WebApi 项目框架搭建:目录 为什么使用Swagger 随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染.后端分离的形态,而且前端技术和后端技 ...

  3. Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2

    1. 引言 各位在开发的过程中肯定遇到过被接口文档折磨的经历,由于 RESTful 接口的轻量化以及低耦合性,我们在修改接口后文档更新不及时,导致接口的调用方(无论是前端还是后端)经常抱怨接口与文档不 ...

  4. .NET Core WebApi帮助文档使用Swagger生成Api说明文档

    Swagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案.简单的说就是一款让你更好的书写API文档的框架. 我们为什么选择 ...

  5. 开源的API文档工具框架——Swagger简介

    初次接触Swagger是在2017年5月,当时公司正好要对整套系统架构进行重新设计,有同事推荐用这个技术框架来规范后台接口的API文档.当时因为架构重构,涉及改造的技术点太多,一时也就没太多精力,把S ...

  6. 开源API文档工具- swagger2 与 smart-doc 比较 与 使用

    工具开源地址 swagger2 : https://swagger.io/ smart-doc: https://www.oschina.net/p/smart-doc  国产 两者的比较 swagg ...

  7. .NET Core:API文档

    安装:Swashbuckle.AspNetCore 启用 XML 注释:右键单击“解决方案资源管理器”中的项目,然后选择“属性”.勾选“生成”选项卡的“输出”部分下的“XML 文档文件”框. 将 Sw ...

  8. api文档工具

    平台选型         Apidoc         文档参考:http://apidocjs.com        优点      文档齐全,操作简单,ui清晰,代码注解查询性强,语言支持多元化, ...

  9. ant design pro (十五)advanced 使用 API 文档工具

    一.概述 原文地址:https://pro.ant.design/docs/api-doc-cn 在日常开发中,往往是前后端分离的,这个时候约定好一套接口标准,前后端各自独立开发,就不会被对方的技术难 ...

随机推荐

  1. 更新Preloader与uboot

    1.用bsp-editor 产生Preloader 参考https://rocketboards.org/foswiki/Documentation/AVGSRD160Preloader 根据QSYS ...

  2. JS基础知识——原型与原型链

    1.如何准确判断一个变量的数组类型 2.写一个原型链继承的例子 3.描述new一个对象的过程 4.zepto(或其他框架中如何使用原型链) 知识点: (1)构造函数 function Foo(name ...

  3. Golang 入门系列(十四)defer, panic和recover用法

    以前讲过golang 的基本语法.但是,只是讲了一些基础的语法,感兴趣的可以看看以前的文章,https://www.cnblogs.com/zhangweizhong/category/1275863 ...

  4. 爬虫(五):代理IP、Cookie

    1. 代理IP 代理IP这个功能呢,在urllib和requests中都存在,但是这个在大的爬虫项目中是非常重要的,所以我拿出来单独讲解. 对于某些网站,如果同一个 IP 短时间内发送大量请求,则可能 ...

  5. 分布式事务之解决方案(TCC)

    4. 分布式事务解决方案之TCC 4.1. 什么是TCC事务 TCC是Try.Confirm.Cancel三个词语的缩写,TCC要求每个分支事务实现三个操作 :预处理Try.确认Confirm.撤销C ...

  6. 微服务与敏捷开发(Scrum/Kanban)的核心思想之我见

    微服务与敏捷开发(Scrum/Kanban)的核心思想之我见   关于"微服务"和"敏捷开发"的文章网络上有很多,所以这里不再重复叙述这些概念的解释和特点,而是 ...

  7. 腾讯云推出一站式 DevOps 解决方案 —— CODING DevOps

    在产业互联网的大背景下,如何将人工智能.大数据等前沿技术与实体产业相结合,推动传统企业转型升级,已经成为每一个企业不得不思考的问题.落后的软件研发能力已经拖慢了中国大量企业的数字化转型进程. 为了满足 ...

  8. 数据结构学习--单链表(python)

    概念 链表(linked_list)是物理存储单元上非连续的.非顺序的存储结构,数据元素的逻辑顺序 是通过链表的指针地址实现,每个元素包含两个结点,一个是存储元素的数据域 (内存空间) ,另一个是指向 ...

  9. Webpack 一些概念

    目录 引子 Dependency Graph Runtime Manifest Module.Bundle.Chunk Bundle Splitting Code Splitting Tree Sha ...

  10. Sqoop 抽数报错: java.io.FileNotFoundException: File does not exist

    Sqoop 抽数报错: java.io.FileNotFoundException: File does not exist 一.错误详情 2019-10-17 20:04:49,080 INFO [ ...