ASP.NET Core 1.0 中使用 Swagger 生成文档

Posted 2020-06-14

github：https://github.com/domaindrivendev/Ahoy

之前文章有介绍在ASP.NET WebAPI 中使用Swagger生成文档，ASP.NET Core 1.0中同样也支持。

依赖包

"dependencies": {
    "Swashbuckle.SwaggerGen": "6.0.0-rc1-final",
    "Swashbuckle.SwaggerUi": "6.0.0-rc1-final"
  }

项目属性选中“生成时生成输出”选项用来生成XML注释

Startup类

public class Startup
    {
        //private readonly string pathXml = @"\\\\Mac\\Home\\Desktop\\asp.net core\\learn_asp.net core 1.0\\artifacts\\bin\\SwaggerForASP.NETCore\\Debug\\dnx451\\SwaggerForASP.NETCore1.0.xml";
        private readonly string pathXml = @"C:\\Users\\irving\\Desktop\\asp.net core\\LearningASP.NETCore\\artifacts\\bin\\LearningASP.NETCore\\Debug\\dnx451\\LearningASP.NETCore.xml";

        public Startup(IHostingEnvironment env)
        {
            // Set up configuration sources.
            var builder = new ConfigurationBuilder()
                .AddJsonFile("appsettings.json")
                .AddEnvironmentVariables();
            Configuration = builder.Build();
        }

        public IConfigurationRoot Configuration { get; set; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            // Add framework services.
            services.AddMvc();

            services.AddSwaggerGen();

            services.ConfigureSwaggerDocument(options =>
            {
                options.SingleApiVersion(new Info
                {
                    License = new License { Name = "irving", Url = @"http://cnblogs.com/irving" },
                    Contact = new Contact { Name = "irving", Email = "[email protected]", Url = @"http://cnblogs.com/irving" },
                    Version = "v1",
                    Title = "ASP.NET Core 1.0 WebAPI",
                    Description = "A Simple For ASP.NET Core 1.0 WebAPI",
                    TermsOfService = "None"
                });
                options.OperationFilter(new ApplyXmlActionComments(pathXml));
            });

            services.ConfigureSwaggerSchema(options =>
            {
                options.IgnoreObsoleteProperties = true;
                options.DescribeAllEnumsAsStrings = true;
                options.ModelFilter(new ApplyXmlTypeComments(pathXml));
            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
        {
            loggerFactory.AddConsole(Configuration.GetSection("Logging"));
            loggerFactory.AddDebug();

            if (env.IsDevelopment())
            {
                app.UseBrowserLink();
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Home/Error");
            }

            app.UseIISPlatformHandler();

            app.UseStaticFiles();

            app.UseMvc(routes =>
            {
                routes.MapRoute(
                    name: "default",
                    template: "{controller=Home}/{action=Index}/{id?}");
            });

            app.UseSwaggerGen();

            app.UseSwaggerUi();
        }

        // Entry point for the application.
        public static void Main(string[] args) => WebApplication.Run<Startup>(args);
    }

OrdersController类

    [Route("api/orders")]
    public class OrdersController : Controller
    {
        [HttpGet]
        [Route("info")]
        public async Task<ActionResult> Info()
        {
            return await Task.Run(() =>
            {
                return Json(new { name = "irving", age = 25 });
            }).ContinueWith(t => t.Result);
        }

        // GET: api/values
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        [HttpGet("{id}")]
        public string Get(int id)
        {
            return "value";
        }

        // POST api/values
        [HttpPost]
        public void Post([FromBody]string value)
        {
        }

        // PUT api/values/5
        [HttpPut("{id}")]
        public void Put(int id, [FromBody]string value)
        {
        }

        // DELETE api/values/5
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }

访问：http://localhost/swagger/ui/index.html

Refer:
http://damienbod.com/2015/12/13/asp-net-5-mvc-6-api-documentation-using-swagger/