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 = 1,username = "fanqi",password = "admin",age = 25,email = "fanqisoft@163.com"},
                new User{ id = 2,username = "gaoxing",password = "admin",age = 22,email = "gaoxing@163.com"}
            };
        }

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