标签: openapi

我使用 OpenAPI 3.0.1，并使用具有类型/值验证的组件。（即类型/枚举/范围）。

当我使用错误的类型/值访问相关路径时，我会收到一条人类无法阅读的默认消息，例如：

"message": "request body has an error: doesn't match the schema: Error at <fieldName>: Doesn't match schema \"oneOf\"".

相反，我想为每个组件创建自定义错误消息，即：

invalid argument: <fieldName>.

Solr 搜索 API 是否有 OpenAPI 规范？

我们的 API 中有一个 Solr 搜索端点，并且喜欢重用任何 OpenAPI 规范。

我目前正在研究 Pact，作为测试策略开发的一部分。它是一个微服务架构，并且有各种服务器到服务器的连接，我可以看到它非常有用（包括消息队列）。

然而，我无法准确理解它应该如何工作的一个地方是客户端和服务器之间的连接。在我们最常见的模式中，我们有一个 Java 微服务，充当 Typescript/Angular Web 客户端的服务器。服务器采用OpenAPI规范；具体来说，我们手动编写 OpenAPI 规范文件，然后从规范文件生成服务器和客户端代码 - 服务器代码是我们期望实现的控制器的一系列接口，客户端代码是服务和模型库客户端可以使用它向服务器发出请求。客户端上的这种模式使 HTTP 请求变得轻而易举，原因如下：

1. 模型和控制器在规范文件中定义并在客户端和服务器之间共享，这意味着我们静态执行合约，因此我们在运行测试之前就知道合约是否被破坏
2. 与服务器交互非常简单，因为生成的控制器服务具有易于使用的 API，可以抽象出主机名、路径等详细信息。

一方面，在此设置中使用 Pact 绝对可以带来一些好处：

1. pact 文件可用于启动存根服务器，然后该存根服务器可用于支持组件测试。
2. 它使我们更加倾向于消费者驱动的合同方法（这通常是好的，但前提是我们真正从中受益）。

另一方面，我也有一些担忧：

1. 我们实际上并不需要 Pact 在测试时提供的语法强制，因为我们在编译时就有了。
2. 遵循 Pact 文档中建立的准则进行的消费者测试本质上会涉及测试生成的服务代码，这感觉……是错误的。不需要测试生成的代码 - 它应该可以正常工作。而且由于我们的合约测试应该反映实际的客户端行为，因此这些测试之一失败的唯一场景（例如，对 API 进行重大更改）将始终与我们实现中的编译时失败同时发生，从而使测试变得不必要。
3. 即使我们要编写所有测试，也不清楚我们将在提供商方面采取什么行动。我们可以根据 OpenAPI 定义验证该协议，但我很确定在给定我们的设置的情况下，我们不可能失败这样的验证（除非手动修改协议文件，这似乎是一个很大的禁忌）。诚然，我还没有对提供商方面进行太多调查。

坦率地说，仅第一个积极因素就足以让我承诺加入 Pact。消费者驱动的方法使得生成存根的过程变得更加有意义。话虽这么说，负面影响肯定会让我感到厌烦。感觉工作量很大，其中大部分是引入冗余验证机制，这样我们就可以获取单一利益。

我这样做是错误的吗？我是否可以对这种方法进行简单的改变，以获得相同的好处而不引入冗余？或者我只需要接受这就是方式？

编辑：所以我开始研究使用契约生成存根服务器的工具，结果发现它非常缺乏。内置的 pact 服务器存根不支持以编程方式向正在运行的服务器添加模拟，而且我发现将 pact 转换为与其他服务器存根库一起使用的大多数库都非常小，并且维护得不是特别好。这意味着我们可能必须为存根过程构建我们自己的解决方案，这使得 Pact 的吸引力更小=/

有什么方法可以在 asp.net core webapi 中支持 oneOf 吗？

我可以在请求正文中支持两种不同的架构吗？

https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#oneof

我正在使用Swashbuckle.AspNetCore.SwaggerGen版本 v6.1.5 的 ASP.NET Core。

我希望像[HttpGet]或[HttpGet("user")]in a public这样的路由swagger.json用于公共端点，而包含internal在像这样的路由内部的其他路由[HttpGet("internal/user/{userGuid}")]位于swagger.json端点的内部实例中。

我在启动时配置 SwaggerConfigureServices如下：

services.AddSwaggerGen(gen =>
{
    gen.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Server API",
        Version = "1.0",
        Description = "This API features all public available endpoints showing different API features."
    });
    gen.SwaggerDoc("v1-internal", new OpenApiInfo
    {
        Title = "Viewer Server API (internal)",
        Version = "v1-internal",
        Description = "This API features all public available endpoints showing different API features." …

有没有办法用 OpenAPI 描述json-lines？

除了似乎还没有 MIME 类型这一事实之外，我想知道是否可以描述这样的响应。

理论上，我的响应可能是一组对象，但我收到了是否可以以 json-lines 形式传递的问题，意思是：只是对象，每行一个。

由于我使用 OpenAPI 来描述我的 API，我对如何描述此响应感到困惑。我可以简单地将响应定义为“字符串”类型，但这对于我的 API 规范的读者来说并不是很有帮助。

让 \xe2\x80\x99s 说我有不同的后端服务，在 azure api 管理 (apim) 中公开它们的 api。不同的服务依赖于不同的安全方法，例如jwt令牌和订阅密钥。后端开发人员指定这些差异并使用 OpenApi 规范 (OAS) 将其上传到 apim。然后我发现安全定义被忽略，那么开发人员必须在哪里指定此信息？而是在描述中？或者在 apim 中传递安全信息的正确方法是什么。

此外，apim 可以设置有关安全的策略。这些政策也没有在美洲国家组织中公开。然而，除了订阅密钥之外，这只是默认行为，即使在 apim 的 api 设置中禁用了需要订阅的标签，订阅密钥仍然存在于 OAS 中。

那么，当 OAS 中不存在后端服务安全性和 apims 安全性时，如何告知用户相关信息呢？我是否缺少某些配置？

我的 apim 的想法是拥有不同的后端服务供应商，这样他们就可以有不同的安全级别 - 可以在 OAS 中指定 - 但不会在 apim 的导出版本中提供任何内容。

此外，我作为 apim 的所有者将设置一些安全设置 - 这些设置仍然不会出现在 OAS 中。那么消费者应该怎么做才能了解如何使用下载的 OAS\xe2\x80\x99s 中公开的后端端点呢？

我正在使用MSW和OpenAPI 后端包。我想模拟展位浏览器服务器和测试服务器。我有 OpenAPI 定义可用的形式，我为 RTK 查询生成 generated.ts （超出了这个问题的范围）。我想使用 OpenAPI 规范将其与 OpenAPI 后端一起使用，并为浏览器和测试生成 MSW 休息工作人员。

接下来是设置：

索引.tsx

import worker from './mocks/browser';

if (process.env.NODE_ENV === 'development') {
    worker.start();
}

模拟/浏览器.ts

import { setupWorker, rest } from 'msw';

import { OpenAPIBackend } from 'openapi-backend';
import type { Document } from 'openapi-backend';
import definition from './api.json';


// create our mock backend with openapi-backend
const api = new OpenAPIBackend({ definition: definition as Document });
api.register('notFound', (c, res, ctx) => res(ctx.status(404)));
api.registerHandler('notImplemented', …

我有以下课程

export class DocumentsSteps {
    @ApiProperty({type: ???})
    [type: string]: DocumentStep;
}

我应该如何定义 ApiProperty 类型？

我创建了一个名为的自定义字段，它使用上传的图像创建缩略图，并在我的模型用户模型PictureField中使用它：User

class User(AbstractBaseUser):
    profile_image = PictureField(make_thumbnail=True)

{
    "image": {
      "url": "string",
      "name": "string"
    },
    "thumbnail": {
      "url": "string",
      "name": "string"
    } | None
}

@extend_schema_field(OpenApiTypes.BINARY)
class PictureSerializerField(ImageField):
     ...

@extend_schema_field({
    'request':OpenApiTypes.BINARY,
    'response': {}# My output example that I said above
})