基于.NetCore3.1系列 —— 使用Swagger作Api文档 (上篇)

前言

  为何在开发中，接口文档愈来愈成为先后端开发人员沟通的枢纽呢？

  随着业务的发张，项目愈来愈多，而对于支撑整个项目架构体系而言，咱们对系统业务的水平拆分，垂直分层，让业务系统更加清晰，从而产生一系统平台和系统，并使用接口进行数据交互。所以可见，业务的不断发展，接口不断增多，不少接口各自寄宿在不一样的项目中，若是没有使用api工具进行管理，那么使用和说明将变得很是复杂。因此，接口管理运营应运而生。

  在过去的开发中，没有API文档管理工具以前，不少的API文档在什么地方写的都有，有在word写的，有在excel写的，也有对应的项目目录下readme.md写的，每一个公司都有每一个公司的玩法，可是文档规范极其不统一，甚至出现开发接口更新，但文档不更新，最终致使代码和接口不匹配，开发功能出问题。撸码一分钟，对接三小时。这每每是你们最痛苦的。    

                     

  所以，在先后端分离的状况下，怎样让先后端开发人员更容易、更直观、更舒服的方式进行沟通交流。在这里，推荐一款轻量级的项目框架Swagger给你们使用。Swagger就是一款让你更好书写API文档的框架

开始

1、 引用Swagger的nuget包

  Swashbuckle.AspNetCore

 而后就在项目的Nuget依赖里看到刚刚引入的Swagger

2、服务配置环节

在Startup.cs页面中：

编辑 ConfigureServices 类：

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    Version = "V1",   //版本 
                    Title = $"XUnit.Core 接口文档-NetCore3.1",  //标题
                    Description = $"XUnit.Core Http API v1",    //描述
                    Contact = new OpenApiContact { Name = "艾三元", Email = "", Url = new Uri("http://i3yuan.cnblogs.com") },  
                    License = new OpenApiLicense { Name = "艾三元许可证", Url = new Uri("http://i3yuan.cnblogs.com") }
                });
            });
            services.AddControllers();
        }

其中的Url地址不能为空。

3、中间件启动环节

编辑Configure类

注意：路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件,注意localhost:8001/swagger是访问不到的，去launchSettings.json把launchUrl去掉，若是你想换一个路径，直接写名字便可，好比直接写c.RoutePrefix = "swagger";

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseSwagger();
            app.UseSwaggerUI(c => {
                c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"XUnit.Core V1");
                c.RoutePrefix = string.Empty;     //若是是为空 访问路径就为 根域名/index.html,注意localhost:8001/swagger是访问不到的
                //路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件
                // c.RoutePrefix = "swagger"; // 若是你想换一个路径，直接写名字便可，好比直接写c.RoutePrefix = "swagger"; 则访问路径为 根域名/swagger/index.html
            });

            app.UseRouting();

            app.UseAuthorization();

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

到这里以后，咱们已经完成了对swagger的添加，F5运行以后，

 运行项目以后，咱们发现官方默认的是 /WeatherForecast地址，因此咱们修改为在域名后面输入/index.html，就能够正常访问了。

若是想修改默认的启动地址，能够在launchSetting.json文件中的launchUrl设置为空，或者删除掉就能够了。

 这个时候咱们再次启动项目，就能够直接访问根目录下的文件了。

若是启动应用，并导航到 http://localhost:<port>/swagger/V1/swagger.json。 生成的描述终结点的文档显示以下json格式。

补充

  1. 已经有接口了，但如何添加注释呢？

  2. 做为接口使用者，咱们关心的是接口的返回内容和响应类型，那咱们如何定义描述响应类型呢？

  3. 在项目开发中，使用的实体类，又如何在Swagger中展现呢？

  4. 在部署项目，引用Swagger既有文档又不须要额外部署，可是如何在开发环境中使用，而在生产环境中禁用呢？

 

以上的这些内容，会在下一篇讲解Swagger作Api文档作详解。

好了，今天的使用Swagger作Api文档上篇内容就说到这里了，但愿能给你们在使用Core开发项目中使用Swagger生产接口文档带来帮助。

总结

 1. 从过去手写Api文档，到引入Swagger工具自动生产API接口说明文档，这一转换，让更多的接口能够以通俗易懂的方式展示给开发人员。

 2. 后续会继续介绍Swagger的一些高级用法，但愿对你们使用Swagger有所帮助。