工作中一个公司会有很多个项目,项目之间的交互经常需要编写 API 来实现,但是编写文档是一件繁琐耗时的工作,并且随着 API 的迭代,每次都需要去更新维护接口文档,很多时候由于忘记或者人员交替的愿意造成接口文档与代码不一致。

  在实际工作中,有的公司会有强制的代码规范,要求代码必须要有注释以及字段、方法、类、接口等的命名规范。但是很多小公司是不存在的,即使按照了规范编写代码也还是需要额外去维护一个文档(word、Excel、markdown等方式),用来提供给其他系统或前端的调用,非常耗时。

  那么有什么方法可以快速生成文档并且使其跟随代码的迭代而变化呢?答案是可以是用Swagger,Swagger工具可以帮助完成生成和维护API文档的工作,确保文档在API发展过程中保持最新状态。

  Swagger官网主要提供了几种开源工具:Swagger Codegen可以通过为API生成服务器或客户端代码;Swagger UI提供一个可视化的UI页面展示使得接口的调用方等人可以在该页面对相关接口进行查阅和做一些简单的请求;Swagger Editor类似于markendown编辑器的编辑Swagger描述文件的编辑器,该编辑支持实时预览描述文件的更新效果;Swagger Inspector 是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求,会返回更多的信息,也会保存你请求的实际请求参数等数据;Swagger Hub集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。具体可查看官网:https://swagger.io/

  这里我们只展示在Asp.net core 中 如何 集成 Swagger。

  新建.net core 2.2 的Api项目SWagger.Api,首先在asp.net core中使用Swagger我们需要引入Nuget包 Swashbuckle.AspNetCore。

Install-Package Swashbuckle.AspNetCore

  新建控制器UserController,并且实现Get、Put、Post、Delete方法,方法需要指定具体的属性和添加必要的注释。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc; namespace Swagger.Api.Controllers
{
/// <summary>
/// 用户接口
/// </summary>
[Route("api/[controller]")]
[ApiController]
public class UserController : Controller
{
/// <summary>
/// 获取所有用户的信息
/// </summary>
/// <returns>所有用户</returns>
[HttpGet]
[Route("")]
public IActionResult Get()
{
return Json(new { Id=,Name="Jesen",Email="jesen@qq.com" });
} /// <summary>
/// 通过用户Id获取用户信息
/// </summary>
/// <remarks>
/// id必须传值
/// </remarks>
/// <param name="id">用户Id</param>
/// <returns>用户信息</returns>
/// <response code="200">返回用户信息</response>
/// <response code="400">如果id为空</response>
[HttpGet]
[Route("{id}")]
[ProducesResponseType()]
[ProducesResponseType()]
public async Task<IActionResult> Get(int? id)
{
if (id == null) return BadRequest(); return Json(new { Id = id, Name = "Jesen", Email = "jesen@qq.com" });
} /// <summary>
/// 添加用户
/// </summary>
/// <param name="user">User对象Json</param>
/// <response code="200">返回用户信息</response>
/// <response code="400">错误</response>
[HttpPost]
[ProducesResponseType()]
[ProducesResponseType()]
public async Task<IActionResult> Post([FromBody] User user)
{
return Ok(user);
} /// <summary>
/// 更改用户
/// </summary>
/// <param name="user">User对象Json</param>
/// <returns></returns>
[HttpPut]
public async Task<IActionResult> Put([FromBody] User user)
{
return Ok(user);
} /// <summary>
/// 通过用户Id删除用户
/// </summary>
/// <param name="id">用户Id</param>
/// <returns></returns>
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(int id)
{
return Ok();
}
}
}

  可以看到和我们平常编写接口差不多,不需要做其他的工作,在.net core中集成Swagger需要做的仅仅是在Startup中注入它并且添加该中间件。

public void ConfigureServices(IServiceCollection services)
{
//注册Swagger生成器,定义一个和多个Swagger 文档
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info {
Title = "用户系统接口",
Version = "v1",
Description = "用户系统对外接口",
TermsOfService = "None",
Contact = new Contact
{
Name = "Jesen",
Email = string.Empty,
Url = "http://www.cnblogs.com/jesen1315/"
},
License = new License
{
Name = "许可证名字",
Url = "http://www.cnblogs.com/jesen1315/"
}
}); // 为 Swagger JSON and UI设置xml文档注释路径
var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录(绝对,不受工作目录影响,建议采用此方法获取路径)
var xmlPath = Path.Combine(basePath, "Swagger.Api.xml");
c.IncludeXmlComments(xmlPath);
}); services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
}
 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
} //启用中间件服务生成Swagger作为JSON终结点
app.UseSwagger();
//启用中间件服务对swagger-ui,指定Swagger JSON终结点
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger.Api V1");
}); //app.UseHttpsRedirection();
app.UseMvc();
}

  至此,运行项目就可以在浏览器上访问并简单调试了。

  是不是很简单,Swagger还可以在生成的时候为项目生成xml文档

 

Asp.Net Core集成Swagger的更多相关文章

  1. asp.net core 集成swagger ui

    什么是Swagger? 说swagger 之前,我们先说一下OpenApi 规范. OpenApi 是一种和语言无关的用于描述RESTAPIs 接口功能的一种规范,对RESTAPIs 接口的描述包括: ...

  2. ABP官方文档翻译 6.2.1 ASP.NET Core集成

    ASP.NET Core 介绍 迁移到ASP.NET Core? 启动模板 配置 启动类 模块配置 控制器 应用服务作为控制器 过滤器 授权过滤器 审计Action过滤器 校验过滤器 工作单元Acti ...

  3. asp.net core 集成 log4net 日志框架

    asp.net core 集成 log4net 日志框架 Intro 在 asp.net core 中有些日志我们可能想输出到数据库或文件或elasticsearch等,如果不自己去实现一个 Logg ...

  4. [Abp 源码分析]十七、ASP.NET Core 集成

    0. 简介 整个 Abp 框架最为核心的除了 Abp 库之外,其次就是 Abp.AspNetCore 库了.虽然 Abp 本身是可以用于控制台程序的,不过那样的话 Abp 就基本没什么用,还是需要集合 ...

  5. ASP.NET WebAPI 集成 Swagger 启用 OAuth 2.0 配置问题

    在 ASP.NET WebAPI 集成 Swagger 后,由于接口使用了 IdentityServer 做的认证,调试起来很不方便:看了下 Swashbuckle 的文档 ,是支持 OAuth2.0 ...

  6. Asp.Net Core 集成 Hangfire 配置使用 Redis 存储

    Hangfire 官方支持 MSSQL 与 Redis(Hangfire.Pro.Redis) 两种 ,由于我的数据库是 MYSQL ,粗略查询了一下文档,现在对 .NET Core 支持的并不够好, ...

  7. asp.net core集成MongoDB

    0.目录 整体架构目录:ASP.NET Core分布式项目实战-目录 一.前言及MongoDB的介绍 最近在整合自己的框架,顺便把MongoDBD的最简单CRUD重构一下作为组件化集成到asp.net ...

  8. asp.net core集成CAP(分布式事务总线)

    一.前言 感谢杨晓东大佬为社区贡献的CAP开源项目,传送门在此:.NET Core 事件总线,分布式事务解决方案:CAP 以及 如何在你的项目中集成 CAP[手把手视频教程],之前也在工作中遇到分布式 ...

  9. asp.net core 集成JWT(一)

    [什么是JWT] JSON Web Token(JWT)是目前最流行的跨域身份验证解决方案. JWT的官网地址:https://jwt.io/ 通俗地来讲,JWT是能代表用户身份的令牌,可以使用JWT ...

随机推荐

  1. [转]protobuf的编译安装

    github地址:https://github.com/google/protobuf支持多种语言,有多个语言的版本,本文采用的是在centos7下编译源码进行安装. github上有详细的安装说明: ...

  2. ROS文件系统级

    ROS的安装就不介绍了,官方教程是最好的:点击打开链接 ROS是机器人操作系统,它应该有自己的工程结构,Linux系统的文件系统如下: 而ROS的文件系统级如下: 接下来逐一介绍它们: 1. catk ...

  3. 激活 phpstorm2019.1 win10

    首先添加以下内容到c:\windows\system32\drivers\etc\hosts 文件 0.0.0.0 account.jetbrains.com 0.0.0.0 www.jetbrain ...

  4. python 迷宫问题

    # -*- coding:utf- -*- from collections import deque # 引入队列 maze = [ [,,,,,,,,,], [,,,,,,,,,], [,,,,, ...

  5. Tkinter 之MessageBox弹出框

    一.参数说明 语法 作用 截图 tk.messagebox.showwarning(title='提示', message='你确定要删除吗?') 警告信息弹窗   tk.messagebox.sho ...

  6. 小程序 之自定义tabbar上边框颜色

    一.设置borderStyle 二.设置page样式 page::after{ content: ''; position: fixed; left: 0; bottom: 0; width: 100 ...

  7. ES索引文件和数据文件大小对比——splunk索引文件大小远小于ES,数据文件的压缩比也较ES更低,有趣的现象:ES数据文件zip压缩后大小和splunk的数据文件相当!词典文件tim/tip+倒排doc/pos和cfs文件是索引的大头

    和splunk对比: ES中各个倒排索引文件的分布: 测试说明:ES2.41版本,数据使用500次批量插入,每批数据都不同,大小500条,每条数据50个字段,对应的字符串使用长度为1-10个单词随机生 ...

  8. AWS 配置IPv6

  9. JMeter学习-参数化

    JMeter也有像LR中的参数化,本篇就来介绍下JMeter的参数化如何去实现. 参数化:录制脚本中有登录操作,需要输入用户名和密码,假如系统不允许相同的用户名和密码同时登录,或者想更好的模拟多个用户 ...

  10. centos上安装Python并修复yum

    date: 2019-07-01  18:09:53 author: headsen chen notice: 个人原创 1,安装python3.7: yum install zlib-devel b ...