标签: openapi

我想用 OpenAPI 2.0 (Swagger 2.0) 描述 RESTful 接口的 XML 响应负载。但是，我很难在 OpenAPI 数据模型中描述特定的 XML 标记。

我无法让 Swagger UI 以这种形式创建适当的示例 XML 标签，在开始和结束 XML 标签之间有一个属性和内容：

<Person id="bar">foo</Person>

文档（此处）仅描述了如何为带有子标签 ( type: object) 的标签或带有内容 ( type: string)的标签建模，但不能同时为两者建模。

我试过这个，Swagger 编辑器接受它，没有任何错误或警告：

<Person id="bar">foo</Person>

但它将由 Swagger UI 呈现为以下示例：

<Person id="bar"></Person>

如您所见，其中没有“foo”内容。

我使用Bravado为 petstore 创建 REST API 的 Python 客户端。

我需要执行相同的操作来获取 REST API 的动态 Ruby 客户端。

• 我在操作系统集成 Swagger 页面中看到了一系列工具，但其中大多数似乎是使用 Swagger 进行自动化测试或创建 Swagger/openapi API，而不是创建使用 Swagger API 的客户端。

• Svelte是上面列表中的“来自 Swagger JSON 规范的动态 Ruby API 客户端”。它可能是一个很好的候选者，看起来与我已经使用的Bravado Python 库类似，但是：

  • 看来请求参数验证仅针对基于 URL 的参数进行，因此它不会提供请求，以及针对 Swagger 2.0 规范的响应验证，如下所示。
  • Svelte 返回 Faraday::Request 而不是模型实例。
• Ruby gem OpenAPI是官方的 Ruby 包装器，这正是我们正在寻找的，但目前还没有任何文档 Cf. 主要自述文件：“Active dev. 文档即将推出”
• Excon（感谢 @kevin-burnett 指出它）没有为 Swagger 描述的 API 提供自动包装器，它是一个 HTTP 客户端，对应于 Python 的Requests，因此是一个手动使用 API 的库。

下面是 Python …

使用editor.swagger.io设计API 我发现自己无法添加requestBody属性,收到我无法解决的错误:

Schema error at paths['/projects/{projectId}/user'].post
should NOT have additional properties
additionalProperty: requestBody
Jump to line 91

我不明白我做错了什么,特别是在查看requestBody文档之后.研究给我带来的只是误差误导的倾向.

编辑:从这里的答案显示,看起来编辑器应该使用OpenAPI 2.0,但实际上期望3.0同时返回两者的错误.鉴于我已经包含了一个,我会在使用什么方面使用一些帮助

swagger: "2.0"

在文档开头的行.虽然与测试openapi: 3.0.0作为他的回答所示@Mike,我只是得到关于允许附加属性更多的错误.

这就是产生错误的原因,第91行post:.

/projects/{projectId}/user:
      post:
        tags:
        - projects
        summary: Modify project user.
        operationId: modifyProjectUser
        parameters:
        - name: projectId
          in: path
          description: ID of the project
          required: true
          type: integer
          format: int32
        requestBody:
          content: 
            application/json:
              schema:
              $ref: '#/definitions/User'
        responses:
          "200":
            description: Successful operation
            schema:
              type: array
              items:
                $ref: "#/definitions/User"
        security:
        - …

按规格：

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

规范使用的带有附加元数据的标签列表。标签的顺序可以被解析工具用来反映它们的顺序。并非操作对象使用的所有标记都必须声明。未声明的标签可以随机组织或基于工具的逻辑。列表中的每个标签名称必须是唯一的。

这些标签在解析器中是如何使用的，你能提供一些例子吗？还有为什么需要是独一无二的？

我需要在用C++编写的遗留API接口上创建HTTP API层.我的计划是生成Swagger或开放API文件,然后将其提供给需要编写客户端(将成为新API的使用者)或服务器(旧API的包装器)的一堆项目.

有没有什么可以加快这个要求(除了手动解析它们和创建swagger规范文件)？即使用C++代码生成swagger JSON/YML文件

我正在尝试生成数据以填充我的代码库中的 OpenAPI 3.0 输入。

我有一个用于将文件上传到服务器的休息端点。

我有一个表单作为聚合物 vaadin-upload 组件用于上传文件。路径为/upload-all，表单参数名称为my-attachment。该表单正确地将文件上传到服务器，因此这不是问题。

服务器端点是使用HTML 表单规范中的 XQRS RestXQ 上传文件来实现的。

我正在尝试为 OpenAPI 3.0 UI 创建 OpenAPI JSON 输入以进行分段文件上传。这是我尝试过的：

"/upload-all": {
    "post": {
        "consumes": ["multipart/form-data"],
        "description": "Upload zip file to the server",
        "responses": {
            "content": {
                "application/json": {
                    "schema": {
                        "type": "object"
                    }
                }
            }
        },
        "parameters": [
            {
                "in": "formData",
                "schema": {
                    "type": "array",
                    "items": {
                        "type": "file"
                    }
                },
                "name": "my-attachment"
            }
        ]
    }
},

我收到一个错误，提示表单参数my-attachment未填充。我缺少什么？我在 OpenAPI 网站上找不到明确的规范。 …

我有一个项目（Spring Boot App + Kotlin），我希望有一个Open API 3.0规范（最好在YAML中）。Springfox库很好，但是它们生成Swagger 2.0 JSON。从控制器中的注释生成Open Api 3.0规范的最佳方法是什么？从头开始编写它是唯一的方法吗？

我正在使用从以下依赖项导入的 Swagger/OpenApi V3 注释创建我们应用程序的 API 描述：

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

其中一个注解是一个@Schema注解，它接受一个名为allowableValues允许字符串数组的属性：

@Schema(description = "example", 
        allowableValues = {"exampleV1", "exampleV2"}, 
        example = "exampleV1", required = true)
private String example;

现在我想使用在我们的 Enum 类上构造的自定义方法，该方法返回允许的字符串数组，因此不需要在每次向 Enum 添加类型时添加它。这样我们就可以像这样使用它：

public enum ExampleEnum {
    EXAMPLEV1, EXAMPLEV2;
    public static String[] getValues() {...}
}

@Schema(description = "example", 
        allowableValues = ExampleEnum.getValues(), 
        example = "exampleV1", required = true)
private String example;

现在这不会编译，因为在执行注释时该方法是未知的。是否有这样的解决方案允许在 swagger V3 注释属性值中使用枚举？

查看以下资源：

• https://swagger.io/docs/specification/data-models/enums/

您可以在全局组件部分定义可重用的枚举，并通过 $ref 其他地方引用它们。

最坏的情况是，我确实可以在一个常量位置定义它，并且在将类型添加到 Enum 之后，只需要在另一个位置添加类型。但如果可能的话，我首先想探索上述解决方案。

• https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#schema

没有说明使用任何类或动态生成的值。

• 大摇大摆的枚举

是关于在 …

我最近在学习 OpenAPI，想了解最佳实践。假设我有一个名为 的资源Person，它的定义components/schemas如下：

Person:
  type: object
  required:
    - id
    - name
    - age
  properties:
    id:
      readOnly: true
      type: integer
    name:
      type: string
    age:
      type: integer

我已将idreadOnly设为只读，因为当我执行postor 时patch，ID 将作为 URL 的一部分传递。请参阅https://swagger.io/docs/specification/data-models/data-types/

name并且age必须在客户端尝试使用post方法创建新人员或get人员时出现，因此它们被定义为required。

我的问题是patch：如果我只想更新一个人的age或name独立的怎么办？理想情况下，我想做类似的事情

PATCH /person/1

{"age": 40}

但是，由于我已name按要求进行了定义，因此我无法做到。我可以想到几种解决方案，但它们都有缺陷：

1. 解除required限制。但如果我这样做，我将失去对post和的验证get。
2. 为 使用单独的模式patch，例如PersonUpdate，使用required删除。显然，这会导致冗余。 …

Swagger 文档说你可以这样做：

https://swagger.io/docs/specification/grouping-operations-with-tags/

但不幸的是 drf-yasg 没有实现这个功能：

https://github.com/axnsan12/drf-yasg/issues/454

据说，我可以添加自定义生成器类，但这是一个非常笼统的答案。现在我看到了drf_yasg.openapi.Swaggerget infoblock 并且我有想法，这可能是将全局tags部分作为附加 init 参数的正确位置，但它比自定义生成器类更深入，而且我对此模块缺乏了解

有没有人有解决这个特定问题的方法，或者至少可能是某种教程的链接，如何正确自定义生成器类？