ASP.NET Core WebApi使用Swagger生成API说明文档【特性版】

⒈新建ASP.NET Core WebAPi项目

⒉添加 NuGet 包

Install-Package Swashbuckle.AspNetCore

⒊Startup中配置

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

 namespace SwaggerDemo
 {
     public class Startup
     {
         public Startup(IConfiguration configuration)
         {
             Configuration = configuration;
         }

         public IConfiguration Configuration { get; }

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

             //注册Swagger生成器，定义一个和多个Swagger 文档
             services.AddSwaggerGen(option =>
             {
                 //配置第一个Doc
                 option.SwaggerDoc("v1", new Info
                 {
                     Version = "v1",
                     Title = "My API_1"
                 });
             });
         }

         // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
         public void Configure(IApplicationBuilder app, IHostingEnvironment env)
         {
             if (env.IsDevelopment())
             {
                 app.UseDeveloperExceptionPage();
             }

             //启用中间件服务生成Swagger作为JSON终结点
             app.UseSwagger();

             //启用中间件服务对swagger-ui，指定Swagger JSON终结点
             app.UseSwaggerUI(c =>
             {
                 c.SwaggerEndpoint("/swagger/v1/swagger.json", "DemoAPI V1");
                 //c.RoutePrefix = "swagger";  //默认
                 c.RoutePrefix = string.Empty;
             });

             app.UseMvc();
         }
     }
 }

⒋添加 特性相关NuGet 包

 Install-Package Swashbuckle.AspNetCore.Annotations

⒌修改Startup中的ConfigureServices方法，启用特性支持

         public void ConfigureServices(IServiceCollection services)
         {
             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

             //注册Swagger生成器，定义一个和多个Swagger 文档
             services.AddSwaggerGen(option =>
             {
                 //配置第一个Doc
                 option.SwaggerDoc("v1", new Info
                 {
                     Version = "v1",
                     Title = "My API_1"
                 });
                 //启用特性支持
                 option.EnableAnnotations();
             });
         }

⒍一些示范

 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using SwaggerDemo.Models;
 using Swashbuckle.AspNetCore.Annotations;

 namespace SwaggerDemo.Controllers
 {
     [Route("api/[controller]")]
     [ApiController]
     [SwaggerTag("用户控制器")]
     public class UserController : ControllerBase
     {
         [HttpGet("get")]
         [SwaggerOperation(Summary = "获取用户列表",Description = "获取系统中所有用户信息",OperationId = "GetUsers")]
         public IList<User> GetUsers()
         {
             return new List<User>
             {
                 new User{ id = ,username = "fanqi",password = "admin",age = ,email = "[e-mail]"},
                 new User{ id = ,username = "gaoxing",password = "admin",age = ,email = "[e-mail]"}
             };
         }

         [SwaggerResponse(, "用户创建成功"]
         [SwaggerResponse(, "用户创建失败")]
         [SwaggerOperation(Summary = "新建用户信息", Description = "新建用户信息", OperationId = "CreateUser")]
         [HttpPost("add")]
         public IActionResult CreateUser([FromForm, SwaggerParameter("新建用户数据", Required = true)]User user)
         {
             return Ok();
         }
     }
 }