在.Net Core中使用Swagger制作接口文档

在实际开发过程中后台开发人员与前端（移动端）接口的交流会很频繁。所以需要一个简单的接口文档让双方可以快速定位到问题所在。

Swagger可以当接口调试工具也可以作为简单的接口文档使用。

在传统的asp.net开发WebApi的过程中大家对Swagger应该都会很熟悉。

接下来我为大家带来如何在.Net Core中搭建一个Swagger环境。

效果图：

1.首先我们在NuGet中搜索“Swashbuckle.AspNetCore”然后安装。

2.生成XML文档：

在工程文件上右键->属性->左边选择“生成”->勾中“XML documentation file”选项->保存

完成后重新生成项目会在“binDebug etcoreapp1.0”下面发现一个与工程名称一样的xml文件。

3.在“Startup”类中加入下面代码：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using System.IO;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.Logging;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.PlatformAbstractions;
using Swashbuckle.AspNetCore.Swagger;

namespace online.web
{
    /// <summary>
    /// 
    /// </summary>
    public class Startup
    {
        /// <summary>
        /// 
        /// </summary>
        /// <param name="env"></param>
        public Startup(IHostingEnvironment env)
        {
            var builder = new ConfigurationBuilder()
                .SetBasePath(env.ContentRootPath)
                .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true);

            Configuration = builder.Build();
        }

        /// <summary>
        /// 
        /// </summary>
        public IConfigurationRoot Configuration { get; }

        /// <summary>
        /// 服务
        /// </summary>
        /// <param name="services"></param>
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1",
                    new Info
                    {
                        Title = "广州树童英语API接口文档",
                        Version = "v1",
                        Description = "限用于开发接口调试.",
                        Contact = new Contact
                        {
                            Name = "魏巍",
                            Email = "68235081@qq.com"
                        }
                    }
                 );

                var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "online.web.xml");
                c.IncludeXmlComments(filePath);
            });
        }

        /// <summary>
        /// 中间件
        /// </summary>
        /// <param name="app"></param>
        /// <param name="env"></param>
        /// <param name="loggerFactory"></param>
        public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
        {
            loggerFactory.AddConsole();

            app.UseMiddleware<Middlewares.ExceptionHandlerMiddleware>();

            app.UseMvc();

            app.UseSwagger(c =>
            {
                c.RouteTemplate = "doc/{documentName}/swagger.json";
            });

            app.UseSwaggerUI(c =>
            {
                c.RoutePrefix = "doc";
                c.SwaggerEndpoint("/doc/v1/swagger.json", "API v1");
            });
        }
    }
}

有些与Swagger无关的代码可以删掉。

成功以后访问：“http://192.168.3.190:9000/doc/”

这里我为了访问地址方便把swagger与成了doc。大家也可以换成自己习惯的访问地址。

更多使用方法请看Swashbuckle.AspNetCore类库的地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore