标签: openapi

对于这种格式的api：GET /resource?param=value1&param=value2&param=value3 在open Api 2.0中，我们可以这样指定：

parameters:
    - in: query
      name: color
      type: array
      collectionFormat: multi
      items:
        type: string 

但在 v3.0 中，属性 collectionFormat 不可用。因此，在尝试使用 collectionFormat 时，我收到错误消息 should not have additional property: collectionFormat。

我搜索了文档但找不到任何答案。有谁知道从 2.0 版本迁移到 3.0 版本的新实现应该是什么？

我有一个 API 的三个路径变量。我想用 ***** 屏蔽 Swagger UI 上的一个输入。

使用 Springdoc OpenAPI 时如何做到这一点？

我决定在Python的FastApi框架中制作一个微服务网关。drf-yasg我的授权服务是用 Django 编写的，并且已经由包 swagger 文档生成。我在想是否有一种方法可以将身份验证的模式导入网关。我可以通过 http 格式提供模式json并从网关访问它。问题是如何将 FastApi 的文档与原始 swagger 模式文件集成。

我有一个 spring（启动）服务器，想要使用 springdoc 从注释生成 OpenAPI 规范。

我有一个请求，请求正文中有两个参数。我希望第一个是必需的，第二个是可选的。

@RequestBody(required = {true|false})似乎只将主体中的所有参数设置为（不需要）。@Parameter另一方面，Javadoc说要使用io.swagger.v3.oas.annotations.parameters.RequestBody

这是我的代码，我希望生成一个规范，其中第一个参数是必需的，第二个参数是可选的：

@GetMapping("/fstVector")
public ResponseEntity<Vector> fstV(@RequestBody final Vector v1, @RequestBody(required = false) final Vector v2) {
    return new ResponseEntity<>(v1, HttpStatus.OK);
}

@PostMapping("/fstVector")
public ResponseEntity<Vector> fstVPost(@RequestBody(required = true) final Vector v1, @RequestBody(required = false) final Vector v2) {
    return new ResponseEntity<>(v1, HttpStatus.OK);
}

然而，生成的规范需要两个参数：

  /pond/fstVector:
    get:
      tags:
      - circle-escape-controller
      operationId: fstV
      parameters:
      - name: v1
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Vector'
      - name: v2
        in: query
        required: …

假设在我的 OpenAPI v3 描述中，我有以下/componenets/schemas条目（使用 YAML）格式：

WidgetTypes:\n  type: string\n  enum:\n    - WIDGET_A\n    - WIDGET_B\n    - WIDGET_C\n

因此，模式WidgetTypes是一个命名的（即值$ref）枚举“类”。在 API 规范的其他各个地方，我们现在可以引用这些枚举值，例如，也许有一个 API 路径，其中一个路径元素必须来自该WidgetTypes集合。

现在，我还有一些附加模式（即对象数据模型），并且可能存在特定 WidgetType值是该对象类型的常量的情况。一个例子：

MySpecificWidgetA:\n  type: object\n  properties:\n    someField1:\n      type: string\n    someField2:\n      type: number\n    widgetType:\n      type: string\n      enum:\n        - WIDGET_A\n

这感觉就像是完成此操作的 na\xc3\xafve 方法，因为 now 的MySpecificWidgetA字段widgetType是来自可能的集合的字符串WidgetType，但没有实际参考强制WidgetType执行此操作。\n本质上，我想要什么要断言的是，这MySpecificWidgetA.widgetType是枚举模式中的特定值WidgetType（在本例中WIDGET_A）。\nUsing 只是$ref: '#/components/schemas/WidgetType' …

我有一个枚举：

public enum UserType {
  ADMIN("Admin"),
  GUEST("Guest"),
  SUPERVIOR("Supervisor"),
  NORMAL("Normal");

  private final String type;

  UserType(final String type) {
    this.type = type;
  }

我将它用作带有 Swagger 注释的查询参数：

@GET
@AsyncTimed
@Path("/all")
void all(
    @ApiParam @PathParam(USER_ID) @Parameter(in = ParameterIn.PATH, name = USER_ID, required = true) final UserId userId,
    @QueryParam(TYPES) final Set<UserType> userTypes,
    @Suspended final AsyncResponse asyncResponse
);

然而，生成的 OpenAPI 文件并没有从枚举中创建组件，而是给出：

get:
  parameters:
  - name: UserId
    in: path
    required: true
    schema:
      $ref: '#/components/schemas/UserId'
  - name: Types
    in: query
    schema:
      uniqueItems: true
      type: array
      items:
        type: string …

例如，不同包中有两个具有相同名称 Group 的类。但是，当在 swagger ui 中引用模型时，仅显示一个模型，甚至响应映射也不正确，swagger 错误地引用了这些模型。

如果我使用依赖系统，有没有办法将字段描述添加到 FastAPI swagger 模式？

我发现没有地方可以在FastAPI 文档的简单示例中添加描述

async def common_parameters(q: str = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit} 

有一个带有字段的实体

      cises:
        type: array
        description: An array of brands. The length must match the value of the quantity field, or the array must be empty
        items:
          type: string

代码java

  @SerializedName("cises")
  private List<String> cises = null;

如何使用 swagger codegen 默认设置一个空列表，而不是 null

我已将 Web 服务定义编写为 OpenAPI 文档。我使用的 openapi-generator-maven-plugin 总是生成带有 poms 和 gradle 构建脚本的整个项目，但我只需要 pojos 以及可能生成的 API 客户端。它应该与 JaxB 或 JaxWS 代码生成器同等工作。

那么有没有办法告诉插件只生成Java代码呢？也许还有另一个插件可以完成这项工作？

这是我的配置：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.1.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/my-api.yaml</inputSpec>
                <modelPackage>com.my.path.to.api</modelPackage>
                <generatorName>java</generatorName>
                <generateApis>false</generateApis>
                <generateModels>true</generateModels>
                <generateModelDocumentation>false</generateModelDocumentation>
                <generateModelTests>false</generateModelTests>
                <library>vertx</library>
                <configOptions>
                    <sourceFolder>src/main/java</sourceFolder>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>