当前位置: 首页 > article >正文

.NET 9 中 OpenAPI 替代 Swagger 文档生成

        微软已经放弃了对 .NET 9 中 Swagger UI 包 Swashbuckle 的支持。他们声称该项目“不再由社区所有者积极维护”并且“问题尚未得到解决”。

        这意味着当您使用 .NET 9 模板创建 Web API 时,您将不再拥有 UI 来测试您的 API 端点。

        我们将调查是否可以在 .NET 9 中使用 Swagger UI 以及是否有更好的替代方案。

        在本文中,我们将深入探讨微软在 .NET 9 中引入的开放 API 支持。此支持使应用程序的客户可以方便地理解和编写相应的 API 调用,并轻松与我们的自动 HTTP 客户端代码生成工具(如 Swagger)集成。

什么是开放 API?
        OpenAPI 规范是定义 HTTP API 的广泛接受的标准。它可以帮助开发人员概述 API 的结构,使其更容易与客户端和服务器生成器、测试框架、文档系统等工具集成。借助 .NET 9,ASP.NET Core 现在内置了对基于控制器和最小 API 生成 OpenAPI 文档的支持,这要归功于 Microsoft.AspNetCore.OpenApi 包。

如何使用它?

        这是一个基本的 ASP.NET Core 9 项目示例,演示了如何将 OpenAPI 支持集成到 Program.cs 中。我们已经准备好了所需的设置。

    builder.Services.AddOpenApi();//这将添加依赖项
    app.MapOpenApi();//这将注册一个端点

自定义

        以下代码更新 Open API 文档端点路径。始终确保路径遵循约定为“<pathtodocument>.json”。

        app.MapOpenApi("/openapidocument.json");

        下面的代码更新了文档的描述,将授权标头标记为必需,并添加了一个额外的服务器作为文档的一部分。

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Info.Description = "This is open api demo";

        // Add when authorization headers are required
        var authComponent = new OpenApiComponents
        {
            Headers = new Dictionary<string, OpenApiHeader>
            {
                { "Authorization", new OpenApiHeader { Required = true } }
            }
        };
        document.Components = authComponent;

        // Add new server if app is available at multiple locations
        document.Servers.Add(new OpenApiServer
        {
            Url = "https://appdev.com/",
            Description = "This is dev server"
        });

        return Task.CompletedTask;
    });
});


以下是我们最终的开放 API JSON,可在“https://localhost:7283/openapidocument.json”上找到。

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenAPIDemo | v1",
    "description": "This is open api demo",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://localhost:7283"
    },
    {
      "url": "http://localhost:5196"
    },
    {
      "url": "https://appdev.com/",
      "description": "This is dev server"
    }
  ],
  "paths": {
    "/WeatherForecast": {
      "get": {
        "tags": [
          "WeatherForecast"
        ],
        "operationId": "GetWeatherForecast",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WeatherForecast"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WeatherForecast"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WeatherForecast"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WeatherForecast": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "temperatureC": {
            "type": "integer",
            "format": "int32"
          },
          "temperatureF": {
            "type": "integer",
            "format": "int32"
          },
          "summary": {
            "type": "string",
            "nullable": true
          }
        }
      }
    },
    "headers": {
      "Authorization": {
        "required": true
      }
    }
  },
  "tags": [
    {
      "name": "WeatherForecast"
    }
  ]
}

现在,您可以使用 NSwag.AspNetCore 包或任何其他使用开放 API 规范的包简单地添加 swagger UI。

对于NSwag.AspNetCore来说,需要添加下面的代码。

app.UseSwaggerUi(config =>
{
    config.DocumentPath = "/openapidocument.json";
});

当您尝试 Swagger UI 时,大多数功能都能按预期正常工作。可能需要进行额外的配置或调整以确保所有配置均按预期工作。

下面是一个参考截图。你可能会注意到上面提到的所有内容都是可见的,包括服务器名称和描述等。

希望这篇文章对您有所帮助。请在评论中分享您的想法,以便更好地使用此软件包。

如果您喜欢此文章,请收藏、点赞、评论,谢谢,祝您快乐每一天。  


http://www.kler.cn/a/586884.html

相关文章:

  • apt-get update命令与apt update命令的区别
  • Assembly语言的安全开发
  • AI日报 - 2025年3月16日
  • 深入理解C/C++堆数据结构:从原理到实战
  • netsh实现TCP端口转发
  • 【Mapbox】介绍及基本使用
  • prompt提示词
  • 算法模型全解析:优缺点、场景适配与选择逻辑
  • 机器学习之特征工程
  • Go语言为什么运行比Java快
  • 如何打包数据库mysql数据,并上传到虚拟机上进行部署?
  • 高频面试题(含笔试高频算法整理)基本总结回顾24
  • Vue 计算属性与 Data 属性同名问题深度解析
  • 基于DeepSeek R1的检验检查超声影像综合预约排班和路径最优化研究
  • webpack的构建流程是什么?loader和plugin的区别是什么?
  • Hive SQL 精进系列:一行变多行的 LATERAL VIEW EXPLODE
  • 立创泰山派使用笔记
  • 解决PC串流至IPad Pro时由于分辨率不一致导致的黑边问题和鼠标滚轮反转问题
  • 基于YOLO目标检测 识别 APP页面点击跳转页面加载时间,视频拆帧统计应用场景,场景数获取时间差,前端性能测试和统计
  • 【每日学点HarmonyOS Next知识】图片拖动、动画放大、列表高度、返回键监听、分割线颜色