.NET Core Web API Swagger 文档生成

1
2
3
4
5
6

# 主要的文档生成都在这里
dotnet add package Swashbuckle.AspNetCore --version 4.0.1

# 用来描述请求的相关信息
dotnet add package Swashbuckle.AspNetCore.Annotations --version 4.0.1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Zhihu404API.Dao;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.EntityFrameworkCore;
using Swashbuckle.AspNetCore.Swagger;

namespace XX404API
{
    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);
            services.AddOptions().Configure<AppSettings>(Configuration);
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "XX-404 API", Version = "v1" });
                c.EnableAnnotations();
            });
        }



        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            // 启用Swagger
            app.UseSwagger();
            // 启动Swagger UI
            app.UseSwaggerUI(c =>
            {
                c.RoutePrefix = "docs";
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "Zhihu-404 API");
            });
            app.UseMvc();
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

// HealthController.cs
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;

namespace XX404API.Controllers
{
    [Route("api/v1/health")]
    [ApiController]
    public class HealthController : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

// HealthController.cs
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using Swashbuckle.AspNetCore.Annotations;
using Newtonsoft.Json.Linq;
using RestSharp;

namespace XX404API.Controllers
{
    [ApiController]
    public class ExtendDataController : ControllerBase
    {

        public ExtendDataController()
        {

        }




        [HttpPost("api/v1/extend-data")]
        // 返回值格式会直接序列化这个typeof的类型
        [SwaggerResponse(200, "", typeof(int))]
        // SwaggerParameter会生成请求体的格式
        public ActionResult AddExtendData([FromBody, SwaggerParameter("原始数据")]List<DBExtendData> extendData)
        {
            if(extendData ==null || extendData.Any(a =>a.Id == default(long)))
            {
                throw new Exception("传入数据有误, 请检查每一项数据Id");
            }
            var count = 10;// _extendDataDapper.BulkInsert(extendData);
            return Ok(new { code = 0, data = count });
        }
    }

    class DBExtendData
    {
        [Column("id")]
        [JsonProperty(PropertyName = "id")]
        public long Id { get; set; }

        [Column("create_time")]
        [JsonProperty(PropertyName = "createTime")]
        public DateTime? CreateTime { get; set; }

        [Column("update_time")]
        [JsonProperty(PropertyName = "updateTime")]
        public DateTime? UpdateTime { get; set; } = DateTime.Now;
    }
}