标签: swagger-codegen

我正在使用Swagger 2.0和swagger-codegen(实际上是Maven的swagger-codegen-plugin)来指定,记录和生成API,以Java作为目标语言.

该项目已经设置为构建服务器存根(JAX-RS)和文档,Eclipse识别项目buildPath中生成的代码.

我不确定这里适当的工作流程是什么.: - /

我不认为我应该修改生成的类,否则每当我更改swagger规范时我的更改都会被覆盖,我希望它随着开发的进行而更多地考虑API而改变.

那我该怎么办？继承自生成的类(哪些？)或将它们包含在我自己的类中？

Swagger项目非常适合在每种语言中轻松创建客户端和服务器应用程序,但我不了解如何以适当的方式维护或扩展现有项目.

我正在生成一个Java服务器 - 语言参数是jaxrs-spec.

我已经编写了自己的Mavenpom并使用了swagger-codegen-maven-plugin所以现在我可以直接使用maven生成模型或api.

我看到每次重建项目时,API都会被swagger-codegen插件完全重写.

我需要实现我的应用程序逻辑,目前我没有看到任何其他方式,而不是自定义生成的API源.因此,为了避免在每次构建时丢失我的工作,我可以配置.swagger-codegen-ignore(我做了),但我只是推迟了问题.

因为第一次我必须更新swagger.json,我唯一的选择是重新生成整个API并覆盖我的工作.好吧,我可以使用git并尝试恢复被删除的部分,但实际上是一个丑陋的解决方案.

所以,问题是:

使用swagger-codegen(或一般的Swagger)是否有一种模式,一种如何,一种文档化的方式,允许我添加行为和/或扩展生成的API而不覆盖我的代码？

我正在尝试调整自动生成的Swagger定义中使用的模型的“ displayName”。

这只会影响Swagger名称，这意味着代码中的名称空间将保持不变，而从Swagger UI查看模型时，您会看到一个自定义名称。

当前，从代码返回的模型名称是一个命名空间，如下所示：b.c.d.e.f，我想在代码中添加一个属性，并“屏蔽” Swagger文档的名称，以便在生成文档/ Swagger定义时它将显示为CustomSwaggerName。

我有一些API（C＃）使用的工具包括Swashbuckle（preferred）和SwaggerGen，但是现在，如果可能的话，我想使它在其中任何一种下工作。

我尝试使用看起来正确的属性：

[ResponseType(typeof(Company)),DisplayName("NewCompany")]
[SwaggerResponse(200,"NewCompany",typeof(object))]

没有运气。我还浏览了SwashBuckle git存储库，希望找到一些东西。

图像应有助于进一步解释我正在尝试实现的目标。

我知道这似乎是一个奇怪的用例，但这是针对为我们的AWS API Gateway自动化编写的工具，该工具将使用Swagger定义进行一些比较。

我们使用Swagger编辑器为我们的API规范创建了一个Yaml文件,其中包括基本URL,端点,请求,响应和头信息等.现在我想为这些API实现RESTful Web服务.为此,我正在考虑从这个Yaml文件生成我的Request和Response Java类,并且正在寻找某种代码生成器,最好是我可以在我的Maven项目中使用的maven插件/依赖项.我遇到了swagger,其中讨论了使用swagger-codegen Maven插件,但这是为了生成client我认为生成客户端代码以使用这些RESTful API,但是我需要生成要使用的类用于服务实施.我将使用Java和Spring框架.

我的问题是,当我们有Yaml文件(使用Swagger编辑器创建的API规范)以及可以使用哪些代码生成工具/插件时,在Java中实现RESTful Web服务的最佳实践是什么.

编辑:刚刚遇到这个服务器存根生成器HOWTO,进一步研究它.

我是Swagger的新手，因此遇到了Server Stub一词。我不明白这是什么意思，如果有人为我解释该术语，我将不胜感激。

byte[] 在 swagger 文件中被建模为byte[]. 当使用 swagger codegen 时，我们得到的List<byte[]>不仅仅是byte[]

Swagger.json

"document": {
    "type": "array",
    "items": 
    {
        "type": "string",
        "format": "byte"
    }
}

pom.xml

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.3.1</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/swagger.json</inputSpec>
                <language>java</language>
                <configOptions>
                   <sourceFolder>src/gen/java/main</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

我们能够使用 openApi 文档并使用 spring swagger-codegen 生成 Java 输入类。此外，我们可以在为常见约束（如长度、强制等）生成输入时注入 javax.validation 注释。

我希望将其提升到下一个自定义级别，并能够使用与 Spring 的 @Constraint 注释连接的自定义验证注释来注释生成的输入类。这样我们就可以为我们的项目重用特定的验证。

我希望有一个开箱即用的解决方案。您使用自定义验证注释生成输入类的首选方法是什么？

我想在 Swagger 生成的 API 中使用不同的结果对象进行响应。对象的类型取决于结果代码。但 Swagger codegen 似乎只生成允许返回第一个定义/使用的类型的代码。

在正常和错误情况下返回不同对象的 Swagger 定义示例如下：

swagger: "2.0"
info:
  description: "API"
  version: 1.0.0
  title: Example
host: localhost:8080

schemes:
  - http

paths:
  /exampleCall:
    get:
      operationId: exampleCall
      produces:
        -  application/json
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/exampleResponse'
        400:
          description: Error
          schema:
            $ref: '#/definitions/exampleError'
definitions:
  exampleResponse:
    type: object
    properties:
      result:
        type: string
  exampleError:
    type: object
    properties:
      code:
        type: string

然后由 SwaggerCodeGen 生成以下 API 接口

@Validated
@Api(value = "exampleCall", description = "the exampleCall API")
@RequestMapping(value = "")
public interface …

假设我的 openapi.yml 中有这个定义（这只是一个虚构的示例来描述我遇到的问题）：

components:
  schemas:
    Address:
      type: object
      properties:
        name:
          type: string
        zip:
          type: integer
          format: int64
        town:
          type: string

这将导致生成如下所示的模型代码：

public class Address   {
  @JsonProperty("name")
  private String name = null;

  @JsonProperty("zip")
  private Long zip = null;

  @JsonProperty("town")
  private String town = null;
...

我的问题是，我必须将这个 Pojo 保留在数据库中，并且不存在表Address（让我们假设它被调用Places），并且邮政编码的列被调用zipcode而不是zip.

所以我需要两件事：

• 一种告诉 OpenAPI 有关别名Address=Places和zip=zipcode.
• 一种使此信息更改所创建的代码的方法。例如，对于 Hibernate，这意味着在正确的位置添加@Table(name="Places")和。@Column(name="zipcode")

重要提示：我无法更改 API，预计会坚持使用Address和zip。

这可以做到吗？我检查了规范以及 swagger-codegen …

我可以使用Swashbuckle在我的web api中集成Swagge UI.我也想探索swagger codegen功能.有人可以帮忙 - 我如何将swagger codegen集成到我的web api项目中？或者我需要下载任何工具吗？我希望它能够托管codegen并传递json/raml表单规范以在.net核心中生成客户端.

我无法在上面找到足够的文档.

编辑:我想知道如何在WEBAPI中托管codegen.

谢谢!