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

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

阅读量：4565 次

发布时间：2019-06-08

本文共 4235 字，大约阅读时间需要 14 分钟。

⒈新建ASP.NET Core WebAPi项目

⒉添加 NuGet 包

Install-Package Swashbuckle.AspNetCore

⒊Startup中配置

1 using System; 2 using System.Collections.Generic; 3 using System.Linq; 4 using System.Threading.Tasks; 5 using Microsoft.AspNetCore.Builder; 6 using Microsoft.AspNetCore.Hosting; 7 using Microsoft.AspNetCore.Mvc; 8 using Microsoft.Extensions.Configuration; 9 using Microsoft.Extensions.DependencyInjection;10 using Microsoft.Extensions.Logging;11 using Microsoft.Extensions.Options;12 using Swashbuckle.AspNetCore.Swagger;13 14 namespace SwaggerDemo15 {16     public class Startup17     {18         public Startup(IConfiguration configuration)19         {20             Configuration = configuration;21         }22 23         public IConfiguration Configuration { get; }24 25         // This method gets called by the runtime. Use this method to add services to the container.26         public void ConfigureServices(IServiceCollection services)27         {28             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);29 30             //注册Swagger生成器，定义一个和多个Swagger 文档31             services.AddSwaggerGen(option =>32             {33                 //配置第一个Doc34                 option.SwaggerDoc("v1", new Info35                 {36                     Version = "v1",37                     Title = "My API_1"38                 });39             });40         }41 42         // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.43         public void Configure(IApplicationBuilder app, IHostingEnvironment env)44         {45             if (env.IsDevelopment())46             {47                 app.UseDeveloperExceptionPage();48             }49 50             //启用中间件服务生成Swagger作为JSON终结点51             app.UseSwagger();52 53             //启用中间件服务对swagger-ui，指定Swagger JSON终结点54             app.UseSwaggerUI(c =>55             {56                 c.SwaggerEndpoint("/swagger/v1/swagger.json", "DemoAPI V1");57                 //c.RoutePrefix = "swagger";  //默认58                 c.RoutePrefix = string.Empty;59             });60 61             app.UseMvc();62         }63     }64 }

⒋添加特性相关NuGet 包

1 Install-Package Swashbuckle.AspNetCore.Annotations

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

1         public void ConfigureServices(IServiceCollection services) 2         { 3             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2); 4  5             //注册Swagger生成器，定义一个和多个Swagger 文档 6             services.AddSwaggerGen(option => 7             { 8                 //配置第一个Doc 9                 option.SwaggerDoc("v1", new Info10                 {11                     Version = "v1",12                     Title = "My API_1"13                 });14                 //启用特性支持15                 option.EnableAnnotations();16             });17         }

⒍一些示范

1 using System; 2 using System.Collections.Generic; 3 using System.Linq; 4 using System.Threading.Tasks; 5 using Microsoft.AspNetCore.Http; 6 using Microsoft.AspNetCore.Mvc; 7 using SwaggerDemo.Models; 8 using Swashbuckle.AspNetCore.Annotations; 9 10 namespace SwaggerDemo.Controllers11 {12     [Route("api/[controller]")]13     [ApiController]14     [SwaggerTag("用户控制器")]15     public class UserController : ControllerBase16     {17         [HttpGet("get")]18         [SwaggerOperation(Summary = "获取用户列表",Description = "获取系统中所有用户信息",OperationId = "GetUsers")]19         public IList
     
       GetUsers()20         {21             return new List
      
       22             {23                 new User{ id = 1,username = "fanqi",password = "admin",age = 25,email = "fanqisoft@163.com"},24                 new User{ id = 2,username = "gaoxing",password = "admin",age = 22,email = "gaoxing@163.com"}25             };26         }27 28         [SwaggerResponse(201, "用户创建成功"]29         [SwaggerResponse(400, "用户创建失败")]30         [SwaggerOperation(Summary = "新建用户信息", Description = "新建用户信息", OperationId = "CreateUser")]31         [HttpPost("add")]32         public IActionResult CreateUser([FromForm, SwaggerParameter("新建用户数据", Required = true)]User user)33         {34             return Ok();35         }36     }37 }