NET 5.0 Swagger API 自動生成MarkDown文檔

目錄

• 1、SwaggerDoc引用
  • 主要接口
• 2、Startup配置
  • 注冊SwaggerDoc服務
  • 注冊Swagger服務
  • 引用Swagger中間件
• 3、生成MarkDown
• 4、生成示例
• 5、MarkDown轉PDF
• 完整項目示例

基於 Swashbuckle.AspNetCore ，根據SwaggerGenerators生成的文檔生成 MarkDown 文檔。

文檔功能：

• JSON 數據格式展示 Request 、Response 數據結構（支持實體多級引用）
• JSON 數據格式展示 Request Body 、Response Body 示例參數
• 支持原生IDocumentFilter、IOperationFilter、IParameterFilter過濾器

1、SwaggerDoc引用

主要接口

    /// <summary>
    /// ISwaggerDocGenerator
    /// </summary>
    public interface ISwaggerDocGenerator
    {
        /// <summary>
        /// 獲取Swagger流文件
        /// </summary>
        /// <param name="name"></param>
        /// <returns></returns>
        Task<MemoryStream> GetSwaggerDocStreamAsync(string name);
        /// <summary>
        /// 獲取Swagger MarkDown源代碼
        /// </summary>
        /// <param name="name"></param>
        /// <returns></returns>
        string GetSwaggerDoc(string name);
    }

2、Startup配置

注冊SwaggerDoc服務

          services.AddSwaggerDoc();//（用於MarkDown生成）

注冊Swagger服務

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "Swagger API 示例文檔", Version = "v1",Description="API文檔全部由代碼自動生成" });
                c.IncludeXmlComments("Samples.xml");
            });

引用Swagger中間件

            app.UseSwagger();
            app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "Samples v1"));

3、生成MarkDown

    /// <summary>
    /// SwaggerController
    /// </summary>
    [ApiController]
    public class SwaggerController : ControllerBase
    {
        /// <summary>
        /// API文檔導出
        /// </summary>
        [HttpGet("/doc")]
        public async Task<IActionResult> Doc([FromServices] ISwaggerDocGenerator swaggerDocGenerator, [FromServices] IWebHostEnvironment environment)
        {
            Stopwatch stopwatch = new Stopwatch();
            stopwatch.Start();
            var stream = await swaggerDocGenerator.GetSwaggerDocStreamAsync("v1");
            stopwatch.Stop();
            var log = "Swagger文檔導出成功，耗時" + stopwatch.ElapsedMilliseconds + "ms";
            Debug.WriteLine(log);
            var mime = "application/octet-stream";
            var name = "SwaggerDoc.md";
            return File(stream.ToArray(), mime, name);
        }
    }

4、生成示例

5、MarkDown轉PDF

我是用的是 typora 編輯器，下載 pandoc 插件可以實現Marddown格式轉換為PDF功能（免費）

如果需要樣式調整，可以去theme 選選

完整項目示例

地址（可以直接運行）： https://github.com/lwc1st/SwaggerDoc