标签: openapi-generator

我最近升级了我的项目以使用 spring-boot 3.0.0。所以我的javax.*项目中不再有模块了。但开放 API 生成器不断尝试导入javax模块。特别是，它用于项目中不再存在的注释javax.annotation.Generated。@Generated有没有办法以某种方式重新配置它？

是否有将 OpenAPI 3.0 转换为 Swagger 2.0 的生成器？

Mashery 是一个 API 网关，在打开端点的输入上需要 Swagger 2.0 格式。

我迷失在依赖项和工具中：我以前使用以下工具为我的 swagger webservices 生成代码。

招摇-codegen-cli

• https://mvnrepository.com/artifact/io.swagger.codegen.v3/swagger-codegen-cli/3.0.13
• https://github.com/swagger-api/swagger-codegen

然后我注意到了以下工具，并认为这是继任者：

openapi 工具生成器

• https://github.com/OpenAPITools/openapi-generator
• https://openapi-generator.tech/docs/installation.html

但是生成的代码使用了不同的注释并且看起来更旧。

有人能告诉我，这两个工具是否相互关联，哪个是最新版本？

我正在使用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 = …

当我从 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 开发方法的背景下找不到好的答案。对此的任何见解都会非常有帮助。

我正在使用 Open API 代码生成器 Maven 插件从文件生成 Open API 3.0。我在我的 pom.xml 中使用这个插件：

<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.3.0</version>

该插件生成 API 时没有任何问题，但它不使用 Swagger v3 注释，而是使用旧的 Swagger 注释。例如，参数使用 进行注释@ApiParam，而@Parameter应使用io.swagger.v3.oas.annotations包中的注释：

default ResponseEntity<Fault> getFault(@ApiParam(value = "",required=true) @PathVariable("jobId") String jobId) {

因此，最新的 Swagger UI 无法正确显示文档。当我使用 swagger.v3 注释创建端点时，Swagger UI 可以正常工作。

根据官方网站https://openapi-generator.tech/docs/plugins/，我应该包含这个依赖项：

<dependency>
    <groupId>io.swagger.parser.v3</groupId>
    <artifactId>swagger-parser</artifactId>
</dependency>

但即使有这种依赖性，插件仍然会生成带有旧注释的源。

如何强制 Open API 代码生成器使用 Swagger v3 注释？

Swagger Code Generator可以生成多种语言的SDK(下面列出的是Github项目页面).有没有人在生产中使用Swagger的任何自动生成的SDK,包括alpha/beta和GA,如果有的话,有哪些组织和什么语言？

我做了一些Google搜索并询问了一下.虽然我发现了许多Swagger UI的部署示例,但我还没有找到任何Code Gen SDK.

项目页面:https://github.com/swagger-api/swagger-codegen

语言:

$ ls -1 modules/swagger-codegen/src/main/java/com/wordnik/swagger/codegen/languages/
AndroidClientCodegen.java
AsyncScalaClientCodegen.java
CSharpClientCodegen.java
JavaClientCodegen.java
JaxRSServerCodegen.java
NodeJSServerCodegen.java
ObjcClientCodegen.java
PhpClientCodegen.java
PythonClientCodegen.java
RubyClientCodegen.java
ScalaClientCodegen.java
ScalatraServerCodegen.java
SpringMVCServerCodegen.java
StaticDocCodegen.java
StaticHtmlGenerator.java
SwaggerGenerator.java
SwaggerYamlGenerator.java
TizenClientCodegen.java

更新 - 主要项目官方SDK跟踪(2018年6月)

我正在跟踪大型组织中可识别的官方codegen SDK,以便更好地跟踪采用情况.许多将自己列为使用某些codegen项目的组织尚未在其GitHub帐户上发布SDK.

• https://github.com/grokify/api-specs/blob/master/official_codegen_sdks.tsv

更新 - 个人经历(2017年12月)

我一直在积极使用Swagger Codegen for Go(2.2.3 - 2.3.1).到目前为止,我的经验是它做得不错,但是需要进行各种手动调整才能获得有效的SDK,因此GitHub包/ repo仍然不错.您可以看到我维护的SDK的GitHub问题中的一些问题.我还将post处理添加到codegen/swagger_codegen_command.sh每个repo中的文件中.

• https://github.com/grokify/go-aha
• https://github.com/grokify/go-ringcentral
• https://github.com/grokify/go-visa
• https://github.com/grokify/go-voicebase-v3

更新 - 添加OpenAPI生成器(2018年7月)

OpenAPI Generator是Swagger Codegen的一个分支,所以现在也提到了这一点.

我正在努力寻找一种解决方案，如何将多个 OpenApi v3 组件定义合并到一个文件中。

让我们想象一个情况：

1. 您决定将 OpenApi 拆分为不同文件夹中的多个文件。（见下图）
2. 现在您需要将所有的 Components.v1.yaml 合并到一个架构中（我将其命名为blueprint.v1.yaml）。通常，我用来swagger-cli合并所有$ref依赖项，但现在不是这样，因为我无法引用整个组件/模式对象列表
3. 并使用它通过工具构建一个填充了所有字段的 OpenApi 文件：信息、组件、路径等swagger-cli bundle。

所以，问题是 - 如何在我的blueprint.v1.yaml文件中重用已定义的组件块（名为 Components.v1.yaml 的文件）？

PS 每个components.v1.yaml看起来都是这样的：

例如，location-create-single.v1.yaml路径定义如下图所示。值得一提的是，所有这些都是$ref指components.v1.yaml文件。

通过org.openapitools:openapi-generator-maven-plugin，我注意到allOf在响应中使用由多个对象组成不会生成组合这些多个对象的类。相反，它使用本节中定义的第一个类allOf。

这是一个最小的例子（openapi.yaml）：

openapi: 3.0.0
info:
  title: Test
  version: v1
paths:
  /test:
    get:
      operationId: get
      responses:
        '200':
          description: Get
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/A'
                  - $ref: '#/components/schemas/B'
components:
  schemas:
    A:
      type: object
      properties:
        attA:
          type: string
    B:
      type: object
      properties:
        attB:
          type: integer

通过以下方式在 Java 中生成类时：

mvn org.openapitools:openapi-generator-maven-plugin:5.2.0:generate \
    -Dopenapi.generator.maven.plugin.inputSpec=openapi.yaml \
    -Dopenapi.generator.maven.plugin.generatorName=java

它显示一个警告：

[WARNING] allOf with multiple schemas defined. Using only the first one: A

正如预期的那样，它生成了类 A 和 B。但是，当调用 时get() …

我希望 OpenAPI 生成器（https://github.com/OpenAPITools/openapi-generator）能够根据 Spring Boot Data 中的实现在 API 中生成 Pageable 参数。我一直在尝试寻找一种合适的开箱即用的解决方案，但找不到。

理想情况下，此 Pageable 参数应仅按以下方式添加到 GET 方法：

default ResponseEntity<User> getUser(@ApiParam(value = "value",required=true) @PathVariable("id") Long id, **Pageable pageable**)

因此，在我的控制器中实现此接口后，我需要重写它并具有上述的 Pageable 参数。我不想有单独的大小或页面参数，这里只有这个可分页。

感谢您的任何提示和帮助！