.net core API 项目中的Swagger的简单使用

1.什么是Swagger

Swagger可以根据你的项目代码，自动生成一套完整的，可视化，可供调试的web服务，可以当做接口文档使用，同时还可以测试接口。

2.为什么要用Swagger

对于一个写api的程序员来说，写接口文档一般也是需要的，以前都是用postman去调试，当然自己测试接口的话，postman依然是一个比较不错的选择，但是当用作一个接口文档给其他同事用的时候，postman就力不从心了。随着api的更新迭代，代码越来越庞大，难免会出现文档和接口对应不上的情况，之后用过apitest，它长这样。

image.png

其实还是挺好用的，可以在线测试接口，多人同时编辑，但是随时而来的还是那个问题，需要手动的维护这些接口文档，那么有没有一种方式，我不需要操心这些文档怎么写的，我只负责写我的代码，接口文档会自己根据我的代码自己修改，那就需要用到swagger了，当然这种框架还有其他的，有兴趣的自己搜一下吧。

3.初步尝试Swagger

话不多说，首先新建一个.net core3.0的api项目，如下图。

image.png

请忽略那个 swagger_demo.xml文件，那个文件是在设置好swagger之后，运行项目自动生成的。
然后在NuGet里找到三个Swagger相关的资源包进行安装。

image.png

安装好之后在依赖项>>包，这里就能看到了。

image.png

接下来就需要添加一些代码了，首先是要注册swagger的服务，在 Startup.cs文件下的 ConfigureServices方法修改如下。

   public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new OpenApiInfo()
                {
                    Title = "Swagger Test UI",
                    Version = "v1",
                    Description = "Aonaufly first ASP.NET Core Web API"
                });
                options.CustomSchemaIds(type => type.FullName); // 解决相同类名会报错的问题
                options.IncludeXmlComments(Path.Combine(Directory.GetCurrentDirectory(), "swagger_demo.xml")); // 标注要使用的 XML 文档
                options.DescribeAllEnumsAsStrings();
            });
        }

然后添加swagger的中间件，还是在Startup.cs文件下，把Configure方法修改如下。

  public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            //设置全局跨域
            app.UseCors(builder => builder.AllowAnyOrigin());
            app.UseHttpsRedirection();
            app.UseSwagger(c => { c.RouteTemplate = "swagger/{documentName}/swagger.json"; });
            // 在这里面可以注入
            app.UseSwaggerUI(options =>
            {
                options.ShowExtensions();
                options.ValidatorUrl(null);
                options.SwaggerEndpoint("/swagger/v1/swagger.json", "Aonaufly API V1");
                options.DocExpansion(DocExpansion.None);
            });

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
           
        }

缺少的命名空间，自己添加一下就好。应该加这三个就行了

using System.IO;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerUI;

然后右键点击项目名称，选择属性，进入到项目属性页，如下图，首先选择生成，下面的输出路径就选择项目路径就好了，注意xml文件名要个代码中的文件名保持一致。

image.png

然后选择生成事件，在生成后事件命令行添加一条命令，注意xml文件名，还是要和上面的保持一致。

copy $(TargetDir)swagger_demo.xml $(ProjectDir)swagger_demo.xml

image.png

，
好了，至此我们可以运行下我们的项目了，这里还是新建项目默认的一个接口。

image.png

在浏览器地址栏输入，就是见证奇迹的时刻了。

https://localhost:5001/swagger

image.png

具体里面的细节等稍后在出文档吧。