.netcore简单集成swagger

为什么要集成Swagger

在前后端分离比较普遍的当下，当后端开发完接口后，还需把接口的信息、参数说明、返回参数等信息编写好提供给调用者。对于对外开放接口需提供说明文档是必不可少的。但是对于内部开发，编写api说明文档非常的繁琐，而且当接口变更或者是有其他人来修改后可能会出现漏更新的情况，导致接口说明文档与实际接口不符的情况发生。

而集成swagger可以实时的展示开放的api以及相关说明（只需要在编码时对代码进行相应的注释即可），而且我们还可以在其上测试提供的api，非常的友好而方便。

需要了解更多的可以访问swagger的官方网站https://swagger.io/。

.netcore简单集成swagger

第一步，创建.netcore WebApi项目，并引入Swashbuckle.AspNetCore

 

第二步，配置项目生成xml说明文档

 

第三步、在startup.cs类中注入并启用swagger

1、在 void ConfigureServices(IServiceCollection services) 方法中添加注入swagger,修改后示例代码

// This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            //添加SwaggerGen，配置api说明xml文档
            services.AddSwaggerGen(p =>
            {
                p.SwaggerDoc("ordercenterapi",
                    new OpenApiInfo { Title = "OrderApi", Version = "v1" }
                    );
                string xmlPath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "QinGy.MarketPlatform.OrderCenterApi.xml"); //程序说明xml文档路径
                //string xmlPath = Path.Combine(AppContext.BaseDirectory, "QinGy.MarketPlatform.OrderCenterApi.xml"); //程序说明xml文档路径
                p.IncludeXmlComments(xmlPath);
            });
        }

 

2、在 void Configure(IApplicationBuilder app, IWebHostEnvironment env) 注册swagger

            //注册swagger插件
            app.UseSwagger(p=>p.RouteTemplate= "{documentName}/swagger.json");

            app.UseSwaggerUI(p =>
            {
                p.SwaggerEndpoint("/ordercenterapi/swagger.json", "orderapi v1");  //注意ordercenterapi是与AddSwaggerGen中指定的名称一致

            });

 

 

编写业务api后运行项目就可以看到继承swagger后的api页面了。

 

---------------------

以上就是.netcore集成swagger的简要说明。

 

附---

1、在启动程序访问时，可能会出现页面报错

 

 

 处理方式：

首先，检查对应的程序生成目录下是否已经生成对应的xml（api的xml）文件。如果没有生成，则检查配置，使其正常生成到程序目录中。

其次，在确保已经征程生成xml文件后，我们可以使用【https://localhost:5001/swagger/v1/swagger.json】（其中5001为对应的端口，v1i是我们设定的对应的name）。这样我们就可以查看详细的错误信息了，然后在做对应的处理即可。（如下，是因为某个controller中的公用接口，没有指定action名称导致的，需加上[HttpPost("addUser")]或者其他）

 

 

 

 

---------------------------------------------------