net core Webapi基础工程搭建（三）——在线接口文档Swagger

目录

• 前言
• Swagger
• NuGet引用第三方类库
• 别急，还有
• 没错，注释
• 小结

前言

先后分离的好处，就是后端埋头作业务逻辑功能，不须要过多考虑用户体验，只专一于数据、性能开发，对于前端须要的数据能够经过组Json或者其余方式回调，可是先后两端须要肯定好接口Api的规范，而且前端若是须要查看接口的相关信息，就须要文档的支撑了。那么问题来了，后端在开发过程当中每次改动接口，都须要改动文档，累不累。

Swagger

Swagger做为一个在线文档，经过后端的接口控制器生成一套Json串数据，实时展现后端的接口请求地址，参数，类型以及回调，很好的解决这个问题（后端能够给前端一个Swagger的地址，而后来句你本身看吧，固然仍是须要多沟通的），这个在Java里用过以后，就立刻看看有没有.net的版本，果真，语言都是相通的，废话很少说，开始第三方类库的引用。

NuGet引用第三方类库

工具->NuGet包管理器->管理解决方案的NuGet程序包...
在浏览中查找"Swashbuckle.AspNetCore"，选择项目工程，点击安装。

引入完成后，在Startup.cs文件ConfigureServices中，加入如下代码：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            
           #region Swagger
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "April WebAPI",
                    Description = "后台框架",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "Blank", Email = "1829027193@qq.com", Url = "http://www.aprilblank.com" }
                });
            });
            #endregion 
        }

在Startup.cs类里编辑Configure方法，加入如下代码：

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
           …
           
            #region Swagger
            app.UseSwagger();
            app.UseSwaggerUI(options =>
            {
                options.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
            });
            #endregion

            app.UseHttpsRedirection();
            app.UseMvc();
        }

从新生成工程后，访问你的端口/swagger就能够看到接口文档帮助界面了。

别急，还有

在线的接口文档是有了，可一个接口啥意思都不知道，前端仍是得一脸懵逼问你，这个接口啥意思啊，这个参数啥意思啊什么的。

没错，注释

仍是在Startup.cs文件ConfigureServices中，加入如下代码：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            #region Swagger
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "April WebAPI",
                    Description = "后台框架",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "Blank", Email = "790048789@qq.com", Url = "http://www.aprilblank.com" }
                });
                
                // 为 Swagger JSON and UI设置xml文档注释路径
                var basePath = Path.GetDirectoryName(AppContext.BaseDirectory);//获取应用程序所在目录（绝对，不受工做目录影响，建议采用此方法获取路径）
                var xmlPath = Path.Combine(basePath, "April.xml");
                options.IncludeXmlComments(xmlPath);
                
            });
            #endregion
        }

右键WebApi这个项目工程，点击属性，在生成这一栏

先拿Values这个控制器作实验

从新生成后会在对应目录看到有Apirl.xml文档文件，运行以后查看/Swagger

点开刚才单独注释参数的/api/Values/{id}

小结

一个WebApi工程离不开文档，而一个在线文档能够省掉本身不少事，而且Swagger也支持在线调试，虽然说我本身仍是倾向于Postman（后续会介绍相关工具），这个在线文档不只是方便了前端查看，总之在开发上确实是一个利器。

下一篇，介绍后台核心之一，Log日志。