工作中一个公司会有很多个项目，项目之间的交互经常需要编写 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=1,Name="Jesen",Email="[email protected]" }); } /// <summary> /// 通过用户Id获取用户信息 /// </summary> /// <remarks> /// id必须传值 /// </remarks> /// <param name="id">用户Id</param> /// <returns>用户信息</リターン> /// <応答コード= "200"> 返回用户信息</レスポンス> /// <応答コード= "400"> 如果ID为空</レスポンス> [HTTPGET] [ルート（" {ID } " ）] [ProducesResponseType（200 ）] [ProducesResponseType（400 ）] パブリック 非同期タスク<IActionResult>（取得int型？ID） { 場合（ID == NULL）を返す）（BadRequestします。 戻り JSON（新しい {ID = IDを、Jesen", Email = "[email protected]" }); } /// <summary> /// 添加用户 /// </summary> /// <param name="user">User对象Json</param> /// <response code="200">返回用户信息</response> /// <response code="400">错误</response> [HttpPost] [ProducesResponseType(200)] [ProducesResponseType(400)] public async Task<IActionResult> Post([FromBody] User user) { 戻りOK（ユーザ）; } /// <まとめ> /// 変化ユーザ /// </要約> /// <PARAM NAME = "ユーザー"> ユーザーオブジェクトJSON </ PARAM> /// <戻り値> </返品> [PUT HTTP] パブリック 非同期タスク<IActionResult> プット（[FromBody】ユーザのユーザ）の { 戻りOK（ユーザ）; } /// <まとめ> /// ユーザIdを介してユーザを削除する /// </要約> /// <PARAM NAME = "ID"> ユーザーID </ param>の /// <リターン> </リターン> [HttpDelete（" {ID} " ）] パブリック 非同期タスク<IActionResult>（削除のint id）を { 返す（OK）を。 } } }
スタートアップでそれを注入することであるとミドルウェアを追加実行する必要が闊歩における.NETのコアで統合された、あなたは、インターフェイスを見ることができますし、我々は通常、書く、他の作業を行う必要はありません。
公共 のボイドConfigureServices（IServiceCollectionサービス） { // 登録闊歩ジェネレータ、および闊歩複数の文書定義 services.AddSwaggerGen（C => { c.SwaggerDoc（「V1 」、新新情報{ タイトル = 「ユーザーインターフェースシステム」、 バージョン = 「V1 」、 説明 = 「ユーザーインターフェイスの外部システム」、 termsOfServiceは = 「なし」、 連絡先 = 新しい連絡先 { 名前 = " Jesen " 、 電子メール = 文字列.Empty、 のURL = " http://www.cnblogs.com/jesen1315/ " }、 ライセンス = 新しいライセンス { 名前 = " 许可证名字" 、 のURL = "http://www.cnblogs.com/jesen1315/ " } }）; // UI提供されるXML文書注釈パスとJSON闊歩の VAR basePathをPath.GetDirectoryName =（typeof演算（プログラム）.Assembly.Location）; // 取得したアプリケーションプログラムディレクトリ（作業ディレクトリ、絶対的ではない、我々は示唆しているパスを取得するためにこの方法を使用して） VAR XMLPath = Path.Combine（basePathを、" Swagger.Api.xml " ）; c.IncludeXmlComments（XMLPath）; }）; services.AddMvc （）.SetCompatibilityVersion（CompatibilityVersion.Version_2_2）; }
公共の 無効設定（アプリケーションIApplicationBuilder、IHostingEnvironment ENV） { IF （env.IsDevelopment（）） { app.UseDeveloperExceptionPage（）; } 他 { // デフォルト値のHSTSが月に30日であるあなたは、このための生産シナリオを変更することで、参照してください。https://aka.ms/aspnetcore-hsts。 app.UseHsts（）; } // JSONエンドポイントとして生成されたミドルウェアサービス闊歩有効 app.UseSwaggerを（）; // ミドルウェアサービス闊歩-UIを有効に指定闊歩JSONエンドポイント app.UseSwaggerUI（C => { c.SwaggerEndpoint（"/swagger/v1/swagger.json", "Swagger.Api V1"); }); //app.UseHttpsRedirection(); app.UseMvc(); }
至此，运行项目就可以在浏览器上访问并简单调试了。
是不是很简单，Swagger还可以在生成的时候为项目生成xml文档
