SwaggerDoc 是一款基于 C# 开发的轻量级工具，专注于生成、管理和展示基于 Swagger 规范的 API 文档。它帮助开发者快速生成高质量的文档，支持 Markdown 格式的输出，易于集成到各种 .NET 项目中，并可扩展为离线 PDF 文档。
- 支持 Swagger 规范：完全兼容 Swagger 规范，支持 RESTful API 的标准化描述。
- 生成 Markdown 格式文档：便于离线保存和分享，支持转换为 PDF 等多种格式。
- 支持复杂嵌套对象结构：能够以 JSON 格式清晰描述复杂的数据结构及其层级关系。
- 高度集成：轻松嵌入 .NET 项目中，支持 .NET 6.0 和 .NET 8.0。
- 定制化文档生成：支持自定义 XML 描述、枚举过滤器以及文档样式调整，满足个性化需求。
- .NET 6.0 或 .NET 8.0。
- 操作系统：Windows 或其他支持 .NET 的平台。
通过 NuGet 安装 SwaggerDoc 包：
dotnet add package SwaggerDoc --version 8.0.1在 Startup.cs 文件中添加以下代码，用于生成 Markdown 文档：
services.AddSwaggerDoc(); // 注册 SwaggerDoc 服务在 Startup.cs 文件中配置 Swagger 服务。注意：项目需开启 XML 文档生成。
- 打开项目的属性，勾选“生成 XML 文档文件”，指定文件名为
Samples.xml。 - 在服务中添加 SwaggerGen 配置：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "Swagger API 文档",
Version = "v1",
Description = "自动生成的 API 文档"
});
// 添加枚举过滤器，显示枚举的描述信息
c.DocumentFilter<SwaggerEnumFilter>(new object[]
{
// 枚举所在的程序集
new[] { Assembly.GetExecutingAssembly() }
});
// 引入 XML 注释
c.IncludeXmlComments("Samples.xml");
});在 Startup.cs 文件的 Configure 方法中添加以下代码：
app.UseSwagger();
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "Samples v1"));访问以下路径以生成 Markdown 文档：
https://{localhost}:{port}/doc?swaggerVersion={swaggerVersion}
- swaggerVersion：Swagger 文档版本（与
SwaggerGen中的Version参数一致，默认为v1）。
以下是生成的 Markdown 和 PDF 示例。
使用 Typora 编辑器，结合 pandoc 插件，将 Markdown 转换为 PDF 文档：
如果需要修改 Markdown 样式，可以参考 Typora 官方主题库 下载自定义主题文件。
欢迎参与本项目开发！贡献方式如下：
- Fork 本项目。
- 创建特性分支：
git checkout -b feature/你的功能描述
- 提交更改：
git commit -m "添加了新功能" - 推送到你的分支：
git push origin feature/你的功能描述
- 发起 Pull Request。
本项目采用 MIT License 进行授权，允许用户自由使用、修改和分发。
- 提交 Issue：GitHub Issues
- 邮箱：[email protected]
Made with ❤️ by liuweichaox