标签: openapi

I\xe2\x80\x99m 正在寻找一种方法来声明 API 中使用的 JSON 对象的扩展元数据，该 API 使用 Swagger/OpenAPI 指定（或者类似的东西，如果有其他格式支持所请求的功能）。

这个想法是使用此元数据自动/部分生成用于编辑此数据的用户界面。

请求的功能列表：

\n

• 对用户可读信息的多语言支持，例如名称、描述、占位符、示例\xe2\x80\x93 API 规范本身的名称和描述可能与最终用户\n例如 CRUD 编辑器应看到的不同。

\n

• 验证元数据
  \n我知道 Swagger/OpenAPI 中有各种字段，例如最小值、最大值、模式等。 \xe2\x80\x93 但无法为验证指定特定的（多语言）错误消息（类似于 \xe2\ x80\x9cA 用户名只能由字母\n和数字\xe2\x80\x9d 以及多种语言的翻译组成。或者\n要匹配的多个模式（每个错误消息都与之相关）。

  \n\n

  另一种验证方法可能是单独的 API 调用（例如\n检查电子邮件或用户名是否可用）

\n

• 关系元数据 例如，ID 字段实际上引用另一个对象的 ID（具有其自己的元数据）。

\n

在 OpenAPI 中，继承是通过allof. 例如，在这个例子中：

  "definitions": {\n    "Pet": {\n      "type": "object",\n      "allOf": [\n        {\n          "$ref": "#/definitions/NewPet"   #\xc2\xa0<--- here\n        },\n        [...]\n      ]\n    },\n    "NewPet": {\n      "type": "object",\n      "properties": {\n        "name": {\n          "type": "string"\n        },\n      }\n    },\n

我在规范中没有找到有关多重继承的任何内容。例如，如果 Pet 继承自 NewPet 和 OldPet。

在Python中，我会写

class Pet(NewPet, OldPet):\n    ...\n

并且方法解析顺序确定了应该首先检查哪个父类的方法/属性，因此我可以判断 Pet.age 是 NewPet.age 还是 OldPet.age。

那么，如果我让 Pet 继承 NewPet 和 OldPet，其中 name 属性在两个模式中都定义，并且每个模式具有不同的值，会怎样呢？宠物名称是什么？

  "definitions": {\n    "Pet": {\n      "type": "object",\n      "allOf": [\n        {\n          "$ref": …

我正在学习 OpenAPI 规范。是否有任何工具可以基于 YAML 格式的 OpenAPI 定义来模拟 API？

我有一个 Spring Boot (kotlin) 项目，我使用 springdoc-openapi 来生成 OpenApi 3 规范。我的数据模型如下所示：

open class Animal
data class Cat(val catName: String) : Animal()
data class Dog(val dogName: String) : Animal()

open class Food<T : Animal>
class CatFood : Food<Cat>()
class DogFood : Food<Dog>()

和一个像这样的简单控制器：

@GetMapping("/test")
fun test(): Food<out Animal> = DogFood()

生成的 yaml 是：

openapi: 3.0.1
info:
  title: OpenAPI definition
  version: v0
servers:
- url: http://localhost:8085
paths:
  /test:
    get:
      tags:
      - test-controller
      operationId: test
      responses:
        "200":
          description: default response
          content:
            '*/*':
              schema:
                $ref: …

我正在使用 Django 和 Django-Drf 来编写一个宁静的 BE。

我还使用 drf-yasg 为我的服务生成 swagger 方案。

不幸的是，drf-yasg 尚不支持 OpenApi3，而且在可预见的未来看起来也不会。

是否有 drf-yasg 的替代方案，它确实支持我可以与 Django-Drf 一起使用的 Openapi 3？

在使用 Kotlin 的 Microprofile / Quarkus 项目中，有一个数据类，其变量类型为 Instant。

@Schema(name = "Vehicle", description = "POJO that represents a vehicle at a specific time.")
data class VehicleDTO(
    var time: Instant = Instant.EPOCH
)

问题是生成的openapi schema并不能代表Instant的值是如何实际传输的。

架构如下所示，而它只是简单地表示为这样的字符串： 2015-06-02T21:34:33.616Z.

Instant:
  type: object
  properties:
    nanos:
      format: int32
      type: integer
    seconds:
      format: int64
      type: integer
    epochSecond:
      format: int64
      type: integer
    nano:
      format: int32
      type: integer

我已经尝试注释数据类以使用实现字符串和类型字符串，但它没有改变任何东西。

@Schema(name = "Vehicle", description = "POJO that represents a vehicle at a specific time.")
data class VehicleDTO(
    @Schema(implementation = String::class, …

我有一个在 .NetCore 3.1 中创建的 API，并使用 Swashbuckle 启用了 Swagger(OAS3)。默认情况下，当我的应用程序启动时，如果使用此 URL 显示 Swagger 页面：

http://{port}/swagger.index.html

我想自定义 Swagger URL，以便它包含正在运行的应用程序的名称。我这样做的原因是我在 AWS Fargate 中运行 Nginx 时使用基于路径的路由。

我将在 Fargate 任务中运行多个 API 容器，Nginx 将接收来自应用程序负载均衡器和路径（例如 /api/app1）的 REST 请求，它将请求路由到目标应用程序的正确容器端口.

例如，我有三个应用程序：端口 5000 上的 App1、端口 5001 上的 App2 和端口 5003 上的 App3。

如果用户向https://api/app1发出请求，Nginx 将检测路径并将请求转发到端口 5000，这是 App1 的容器端口。

但是，为了确保出现正确的 Swagger 页面，我需要在 Swagger 的 URL 中添加“api/App1”，以便 Nginx 将请求转发到正确的容器。在本例中，它是 App1。

换句话说，我希望我的 Swagger URL 看起来像这样：

https://api/app1/swagger/index.html

我试过的

在我的 Startup.cs 文件中，我添加了以下内容：

// Define prefix for application
private readonly string baseApplicationRoute = "api/app1";

            // Enable …

我的 Symfony 4 应用程序中有一个 API 端点，我想用 NelmioApiDocBundle 和 Swagger 记录它。端点将 JSON 作为请求数据，并返回一些自定义 JSON 作为响应。如何使用注释将它们的示例添加到文档中？我在文档页面上看不到任何示例，只有描述。

/**
 * @Route("/order/import", methods={"POST"}, name="order_import")
 * @OA\RequestBody (
 *     request="order",
 *     description="Order data in JSON format",
 *     @OA\Schema(
 *        type="object",
 *        example={"hello": "world"}
 *     )
 * )
 * @OA\Response(
 *     response=200,
 *     description="Returns the JSON data after import",
 *     @OA\Schema(
 *        type="object",
 *        example={"foo": "bar"}
 *     )
 * )
 * @OA\Tag(name="import")

我目前正在使用以下openapi-ui依赖项。

    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.4.4</version>
    </dependency>

如何从openapi-ui swagger屏幕中删除api-resource-controller？