{"id":31136119,"url":"https://github.com/aterdev/aspnetcore.openapi.xml","last_synced_at":"2025-10-29T18:21:50.554Z","repository":{"id":314638551,"uuid":"1056207270","full_name":"AterDev/AspNetCore.OpenApi.Xml","owner":"AterDev","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-13T17:47:39.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-13T19:35:10.337Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AterDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-13T15:59:40.000Z","updated_at":"2025-09-13T17:47:42.000Z","dependencies_parsed_at":"2025-09-13T19:35:12.063Z","dependency_job_id":"f973eb57-1a42-45f0-bed7-1f266bb1bb56","html_url":"https://github.com/AterDev/AspNetCore.OpenApi.Xml","commit_stats":null,"previous_names":["aterdev/aspnetcore.openapi.xml"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/AterDev/AspNetCore.OpenApi.Xml","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AterDev%2FAspNetCore.OpenApi.Xml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AterDev%2FAspNetCore.OpenApi.Xml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AterDev%2FAspNetCore.OpenApi.Xml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AterDev%2FAspNetCore.OpenApi.Xml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AterDev","download_url":"https://codeload.github.com/AterDev/AspNetCore.OpenApi.Xml/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AterDev%2FAspNetCore.OpenApi.Xml/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275732383,"owners_count":25518095,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-18T02:00:09.552Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-18T07:56:14.734Z","updated_at":"2025-10-29T18:21:50.547Z","avatar_url":"https://github.com/AterDev.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AspNetCore.OpenApi.Xml\n\n为 ASP.NET Core 应用提供自定义 XML API 文档生成和 HTML 文档页面。\n\n## 技术栈\n\n- **框架**: ASP.NET Core (基于 .NET 9.0+)\n- **语言**: C# 12+ with Nullable Reference Types\n- **依赖**: Microsoft.AspNetCore.App Framework Reference\n- **序列化**: System.Xml.Serialization\n- **API 探索**: Microsoft.AspNetCore.Mvc.ApiExplorer\n\n## 系统要求\n\n- .NET 9.0 或更高版本\n- 支持的操作系统: Windows, Linux, macOS\n- IDE (可选): Visual Studio 2022, VS Code, Rider\n\n## 开发环境设置\n\n### 1. 安装 .NET SDK\n\n确保已安装 .NET 9.0 SDK 或更高版本：\n\n```bash\ndotnet --version\n```\n\n如需安装，请访问 [.NET 下载页面](https://dotnet.microsoft.com/download)。\n\n### 2. 克隆仓库\n\n```bash\ngit clone https://github.com/AterDev/AspNetCore.OpenApi.Xml.git\ncd AspNetCore.OpenApi.Xml\n```\n\n### 3. 还原依赖\n\n```bash\ndotnet restore\n```\n\n### 4. 构建项目\n\n```bash\ndotnet build\n```\n\n### 5. 运行示例项目\n\n```bash\ncd Demo.WebApi\ndotnet run\n```\n\n访问 `http://localhost:5276/api-doc` 查看生成的文档页面。\n\n## 特性\n\n- ✅ 基于 ASP.NET Core ApiExplorer 自动生成 API 文档\n- ✅ 输出简洁的 XML 格式文档\n- ✅ 提供交互式 HTML 文档页面\n- ✅ 支持类型详情查看（模态框）\n- ✅ 显示验证规则（长度、范围、正则表达式等）\n- ✅ 按控制器分组的接口列表\n- ✅ 响应式设计，GitHub 风格 UI\n\n## 快速开始\n\n### 1. 安装\n\n```bash\ndotnet add package AspNetCore.OpenApi.Xml\n```\n\n### 2. 配置\n\n在 `Program.cs` 中注册服务并映射文档页面：\n\n```csharp\nusing AspNetCore.OpenApi.Xml.Extensions;\n\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddControllers();\n// 注册 API 文档生成器\nbuilder.Services.AddApiXmlDocumentGenerator();\n\nvar app = builder.Build();\n\n// 映射 HTML 文档页面（默认路径: /api-doc）\napp.MapApiDocumentationPage();\n\n// 可选：映射 XML 文档端点\napp.MapGet(\"/__api-doc.xml\", (IApiXmlDocumentGenerator gen) =\u003e\n    Results.Text(gen.GenerateXml(\"My API\", \"v1\"), \"application/xml\"));\n\napp.MapControllers();\napp.Run();\n```\n\n### 3. 访问文档\n\n启动应用后，访问：\n- HTML 文档页面: `http://localhost:5000/api-doc`\n- XML 文档: `http://localhost:5000/__api-doc.xml`\n\n## 文档页面功能\n\n### 接口列表\n- 按控制器分组显示所有接口\n- 支持折叠/展开分组\n- 显示 HTTP 方法（GET、POST、PUT、DELETE 等）\n- 显示路由路径\n\n### 接口详情\n点击接口后显示：\n- HTTP 方法和完整路由\n- 路由参数\n- 查询参数\n- 请求头\n- 请求体（含字段类型和验证规则）\n- 响应格式（状态码、内容类型、响应体）\n\n### 类型查看\n- 点击类型名称打开模态框\n- 查看类型的所有字段\n- 显示验证规则（最小/最大长度、范围、正则表达式等）\n- 支持嵌套类型查看\n- 显示枚举成员及描述\n\n## 自定义配置\n\n### 自定义文档路径\n\n```csharp\napp.MapApiDocumentationPage(\"/docs\");\n```\n\n### 自定义标题和版本\n\n```csharp\napp.MapApiDocumentationPage(\"/api-doc\", \"My Custom API\", \"v2.0\");\n```\n\n### 仅生成 XML 文档\n\n```csharp\npublic class MyController : ControllerBase\n{\n    private readonly IApiXmlDocumentGenerator _generator;\n\n    public MyController(IApiXmlDocumentGenerator generator)\n    {\n        _generator = generator;\n    }\n\n    [HttpGet(\"/api/doc.xml\")]\n    public IActionResult GetXmlDoc()\n    {\n        var xml = _generator.GenerateXml(\"My API\", \"v1\");\n        return Content(xml, \"application/xml\");\n    }\n}\n```\n\n### 程序化使用文档对象\n\n```csharp\npublic class MyService\n{\n    private readonly IApiXmlDocumentGenerator _generator;\n\n    public MyService(IApiXmlDocumentGenerator generator)\n    {\n        _generator = generator;\n    }\n\n    public void ProcessApiDoc()\n    {\n        var document = _generator.Generate(\"My API\", \"v1\");\n        \n        // 访问所有端点\n        foreach (var endpoint in document.Endpoints)\n        {\n            Console.WriteLine($\"{endpoint.Method} {endpoint.Path}\");\n        }\n        \n        // 访问所有模型\n        foreach (var model in document.Models)\n        {\n            Console.WriteLine($\"Model: {model.Name}\");\n        }\n    }\n}\n```\n\n## 示例\n\n查看 `Demo.WebApi` 项目获取完整示例。\n\n运行示例：\n\n```bash\ncd Demo.WebApi\ndotnet run\n```\n\n然后访问 `http://localhost:5276/api-doc`\n\n## 测试\n\n目前项目主要通过 Demo.WebApi 项目进行功能验证。\n\n### 运行测试场景\n\n启动 Demo.WebApi 项目后，可以访问以下端点测试不同功能：\n\n```bash\n# 访问 HTML 文档页面\ncurl http://localhost:5276/api-doc\n\n# 获取 XML 格式文档\ncurl http://localhost:5276/__api-doc.xml\n\n# 测试泛型类型（详见 GENERIC_TESTS.md）\ncurl http://localhost:5276/api/GenericsTest/kvp\ncurl http://localhost:5276/api/GenericsTest/nested-dict\n```\n\n## 项目结构\n\n```\nAspNetCore.OpenApi.Xml/\n├── OpenApi.Xml.Core/              # 核心领域模型和序列化\n│   ├── Models/                    # API 文档数据模型\n│   │   └── ApiDocument.cs        # 文档、端点、请求、响应、Schema 等\n│   └── Serialization/            # XML 序列化/反序列化\n│       └── ApiDocumentSerializer.cs\n├── AspNetCore.OpenApi.Xml/        # ASP.NET Core 集成\n│   ├── Services/                  # 核心服务\n│   │   ├── ApiXmlDocumentGenerator.cs      # 文档生成器\n│   │   └── ApiDocumentationPageService.cs  # HTML 页面服务\n│   └── Extensions/               # DI 和路由扩展\n│       ├── ServiceCollectionExtensions.cs\n│       └── EndpointRouteBuilderExtensions.cs\n└── Demo.WebApi/                   # 演示项目\n    └── Controllers/               # 示例控制器\n```\n\n## 贡献指南\n\n欢迎贡献！请遵循以下准则：\n\n### 代码规范\n\n- 使用 C# 12+ 语法特性（collection expressions, primary constructors, expression-bodied members 等）\n- 启用 Nullable Reference Types (`\u003cNullable\u003eenable\u003c/Nullable\u003e`)\n- 遵循现有代码风格和命名约定\n- 为公共 API 添加 XML 文档注释\n\n### 提交 PR 流程\n\n1. Fork 本仓库\n2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 开启 Pull Request\n\n### 构建检查\n\n在提交 PR 前，请确保：\n\n```bash\n# 构建成功\ndotnet build\n\n# 代码能正常运行\ncd Demo.WebApi\ndotnet run\n```\n\n## 路线图\n\n- [ ] 添加单元测试和集成测试\n- [ ] 支持更多 DataAnnotations 验证规则\n- [ ] 循环引用检测和 $ref 引用支持\n- [ ] 支持导出 Markdown 格式文档\n- [ ] 性能优化（Source Generator 预构建 Schema）\n- [ ] 支持自定义主题和样式\n\n## 常见问题\n\n### Q: 如何自定义文档页面的样式？\n\nA: 目前 HTML 页面使用内联样式。未来版本将支持自定义主题。\n\n### Q: 支持哪些验证规则？\n\nA: 目前支持 `[Required]`、`[StringLength]`、`[Range]`、`[RegularExpression]` 等常用 DataAnnotations。\n\n### Q: 如何处理复杂的泛型类型？\n\nA: 系统支持泛型类型、嵌套泛型、字典等。详见 `Demo.WebApi/GENERIC_TESTS.md`。\n\n## 许可证\n\nMIT License - 详见 [LICENSE](LICENSE) 文件\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faterdev%2Faspnetcore.openapi.xml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faterdev%2Faspnetcore.openapi.xml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faterdev%2Faspnetcore.openapi.xml/lists"}