标签: openapi

我在c#中有一个Asp.Net Web API 5.2项目,并使用Swashbuckle生成文档.

我有一个包含继承的模型,比如从Animal抽象类中获取Animal属性,从中派生出Dog和Cat类.

Swashbuckle只显示Animal类的模式,所以我尝试使用ISchemaFilter(他们也建议),但我无法使它工作,我也找不到合适的例子.

有人可以帮忙吗？

我正在尝试为一个时间间隔构建一个 Swagger 模型，使用一个简单的字符串来存储时间（我知道还有日期时间）：

definitions:
  Time:
    type: string
    description: Time in 24 hour format "hh:mm".
  TimeInterval:
    type: object
    properties:
      lowerBound:
        $ref: "#/definitions/Time"
        description: Lower bound on the time interval.
        default: "00:00"
      upperBound:
        $ref: "#/definitions/Time"
        description: Upper bound on the time interval.
        default: "24:00"        

出于某种原因，生成的 HTML 没有显示lowerBound 和upperBound“描述”，而只显示原始时间“描述”。这让我觉得我没有正确地做这件事。

所以问题是，是否可以像我尝试的那样使用模型作为类型。

很难配置Swagger UI以下是非常简洁的文档:https://django-rest-swagger.readthedocs.io/en/latest/

YAML文档字符串已弃用.有人知道如何从python代码中配置Swagger UI吗？或者我应该将哪个文件更改为组api端点,为每个端点添加注释,在Swagger UI中添加查询参数字段？

我有一个路径,它使用每个http方法具有几乎相同属性的复杂模型.问题是我想为PUT和POST的请求定义一些必需的属性,而GET响应中不需要属性(因为服务器总是返回所有属性,并且在文档的其他地方提到它).

我创建了一个简单的cat API来演示我尝试过的东西.我们的想法是,对于GET响应,响应模型没有标记为必需的任何内容,但PUT的请求必须具有猫的名称.

swagger: "2.0"

info:
  title: "Cat API"
  version: 1.0.0

paths:
  /cats/{id}:
    parameters:
      - name: id
        in: path
        required: true
        type: integer
    get:
      responses:
        200:
          description: Return a cat
          schema:
            $ref: "#/definitions/GetCat"
    put:
      parameters:
        - name: cat
          in: body
          required: true
          schema:
            $ref: "#/definitions/PutCat"
      responses:
        204:
          description: Cat edited

definitions:
  Cat:
    type: object
    properties:
      name:
        type: string
  GetCat:
    allOf:
      - $ref: "#/definitions/Cat"
    properties:
      id:
        type: integer
  PutCat:
    type: object
    required:
      - name
    properties:
      $ref: "#/definitions/Cat/properties"

Swagger编辑说这是一个有效的规范,但是name …

我有一个从 protobuf 生成的 API，我想生成符合 OpenAPI 3 规范的文档。我查看了许多实用程序，但没有找到有效的组合。

有谁知道我可以遵循的从 protobuf 到 OpenAPI 3 的路径？

我正在使用openApi maven 插件为 REST api 生成 java 请求/响应。

该请求有一个 DateTime 属性，当我运行生成器时，我得到了表示为 java.time.OffsetDateTime 的属性的 DateTime 属性。问题是我需要将属性表示为 java.time.Instant。

这是请求的 openApi 规范：

"DocumentDto" : {
      "type" : "object",
      "properties" : {
        "uuid" : {
          "type" : "string",
          "format" : "uuid"
        },
        "creationDate" : {
          "type" : "string",
          "format" : "date-time"
        }
      }
    }

生成的java请求：

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen", date = "2019-05-21T13:07:21.639+02:00[Europe/Zurich]")
public class DocumentDto {
  public static final String SERIALIZED_NAME_UUID = "uuid";
  @SerializedName(SERIALIZED_NAME_UUID)
  private UUID uuid;


  public static final String SERIALIZED_NAME_TEST = …

在 OpenAPI 架构中，它包含可选元素operationId。

这是如何使用的以及为什么它是可选的？好吧，至少对于 .NET Core 库“Swashbuckle”，他们说它是可选的。

我的猜测是它与 SDK 的使用方式有关。例如，我可以从任何有效的 OpenAPI 模式创建 Typescript SDK...所以我猜测它与 Typescript SDK 的生成方式和消费/使用方式有某种联系？

有没有办法从Go源代码生成OpenAPI v3规范？假设我有一个如下所示的 go API，我想从中生成 OpenAPI 规范（yaml 文件）。类似于 Python 的Flask RESTX。我知道有一些工具可以根据规范生成 go 源代码，但是，我想以相反的方式进行。

package main

import "net/http"

func main() {
    http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("world\n"))
    })
    http.ListenAndServe(":5050", nil)
}

当我从 swagger yaml 生成代码时Spring，通常使用模式生成控制器层delegate，这样对于单个模型会生成三个文件。例如，如果我Person在 swagger/open API yaml 文件中定义了一个名为的模型，则会生成三个文件：

1. PersonApi（包含所有人员操作/方法签名的接口）
2. PersonApiDelegate（提供所有 PersonApi 方法的默认实现的接口。意味着要被覆盖）
3. PersonApiController（其中引用了 PersonApiDelegate，以便任何实现都可以覆盖并提供自定义实现）

我的问题是，对于熟悉构建基于 swagger/openapi 生成代码的 api 的人来说，拥有这种模式的意义是什么，而不是仅仅使用 PersonController 类公开服务端点，而不是通过 PersonApi 接口，然后PersonApiDelegate 并最终通过 PersonApiController 公开服务？

我们通过这种模式获得的有价值的设计可扩展性是什么？我试图从互联网上的其他资源中查找信息，但在 swagger-first API 开发方法的背景下找不到好的答案。对此的任何见解都会非常有帮助。

我正在编写一个应用程序，我需要根据逻辑有两组完全不同的响应结构。

有什么方法可以处理这个问题，以便我可以序列化、验证和返回两个不同的响应模型并反映在 OpenAPI JSON 中？

我正在使用 pydantic 来编写模型。