.net core API文档利器swagger的使用

小知识，大挑战！本文正在参与“程序员必备小知识”创作活动。

最近web后台功能完成后需要给移动端写接口，开始api开发的时候居然发现之前的项目居然没有集成api文档工具，这要是完成了api还得一个个去写接口文档？作为一个程序员，写文档，唉。。。。

本着能偷懒就摸鱼的精神，我当然要在借用现成的工具了。

众所周知最受欢迎的REST API文档的生成工具当然就是Swagger了。话不多说，直接开干吧。

首先需要通过NuGet安装swagger的安装包，我们可以在NuGet包管理器中直接搜索Swashbuckle.AspNetCore，也可以在程序包管理控制台中输入命令：Install-Package Swashbuckle.AspNetCore。（PS：后面还是建议用NSwag，因为Swashbuckle目前好像已经不维护了，但是NSwag还一直在更新维护）

安装完成后我们需要先配置一些基本使用规则。 先找到项目的Startup.cs,在ConfigureServices中注册Swager

services.AddSwaggerGen(opptions =>
{
   opptions.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

然后再Configure中启用中间件

app.UseSwagger();
app.UseSwaggerUI(c =>
{
   c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

在我们的Controllers中添加引用

using Swashbuckle.AspNetCore.Swagger;

运行程序，我们在 http://localhost:<port>/swagger/v1/swagger.json中可以看到描述终结点的文档。当然我们也可以直接输入http://localhost:<port>/swagger/index.html浏览swagger UI。不过这里的话我们需要再次设置下: 我们右键项目->属性->生成->输出,勾选XML文档文件并选择输出路径。（为了减少取消警告，我们在上面错误和警告中添加取消显示警告1591） 完成后再次运行就能看到 UI页面了。