标签: swagger-codegen

我正在使用Spring启动创建REST Api,并使用swagger codegen在控制器中自动生成swagger文档.但是,我无法在POST请求中为String类型的参数设置描述和示例.这是mi代码:

import io.swagger.annotations.*;

@Api(value = "transaction", tags = {"transaction"})
@FunctionalInterface
public interface ITransactionsApi {
    @ApiOperation(value = "Places a new transaction on the system.", notes = "Creates a new transaction in the system. See the schema of the Transaction parameter for more information ", tags={ "transaction", })
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Another transaction with the same messageId already exists in the system. No transaction was created."),
        @ApiResponse(code = 201, message = "The transaction has been …

我迷失在依赖项和工具中：我以前使用以下工具为我的 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

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

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

我想使用swagger-codegen生成REST客户端和可能的静态HTML文档.

但是,swagger-codegen需要swagger.json来输入.

我知道,我可以从配备Swagger的运行REST服务器获得这个.

但有没有办法直接从我的Java代码中获取swagger.json - 即从源代码中使用gradle生成它 - 而无需在Web容器中运行应用程序,并指向curl 或浏览器？

正如描述的CORS预检要求失败,因为一个标准的头,如果你发送请求到OPTIONS与端点Origin和Access-Control-Request-Method设置,那么他们得到的Spring框架截获头,和你的方法没有得到执行.接受的解决方案是使用@CrossOrigin注释来阻止Spring返回a 403.但是,我使用Swagger Codegen生成我的API代码,所以我只想禁用它并OPTIONS手动实现我的响应.

那么你可以在Spring中禁用CORS拦截吗？

我正在尝试从swagger.jsonusing生成 java 代码，swagger-codegen-cli.jar但出现此异常：

Exception in thread "main" java.lang.RuntimeException: missing swagger input or config!
        at io.swagger.codegen.DefaultGenerator.generate(DefaultGenerator.java:763)
        at io.swagger.codegen.cmd.Generate.run(Generate.java:299)
        at io.swagger.codegen.SwaggerCodegen.main(SwaggerCodegen.java:35)

我试图运行的命令如下：

java -jar swagger-codegen-cli.jar generate -i swagger.json -l java -c java-config.json -o api-client

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

我有:

1. 一个做[Stuff]的库
2. 一个昂首阔步的API定义,大致相当于#1,只是略有不同,可以干净地映射到REST服务
3. 使用Swagger-Codegen生成#2的烧瓶应用程序 - 例如,导致python控制器函数与#1大致一对一.

我的意图是烧瓶应用程序(所有生成的代码)应该只处理实际REST api和参数解析的映射,以匹配swagger中编码的API规范.在任何参数解析(再次生成代码)之后,它应该直接调用我的(非生成的)后端.

我的问题是,如何通过手工编辑生成的python/flask代码来解决这些问题？(对我的设计的反馈,或实现这一点的正式设计模式的细节也会很棒;我是这个领域的新手).

从发生器新鲜,我最终得到python函数,如:

def create_task(myTaskDefinition):
    """
    comment as specified in swagger.json
    :param myTaskDefinition: json blah blah blah
    :type myTaskDefinition: dict | bytes
    :rtype: ApiResponse
    """
    if connexion.request.is_json:
        myTaskDefinition = MyTaskTypeFromSwagger.from_dict(connexion.request.get_json())
    return 'do some magic!' # swagger codegen inserts this string :)

在后端我有我的实际逻辑:

def create_task_backend(myTaskDefinition):
    # hand-coded, checked into git: do all the things
    return APIResponse(...)

什么是正确的create_task()打电话方式create_task_backend()？

当然,如果我对我的swagger规范进行重大更改,我将不得不手动更新未生成的代码; 但是,我可能想要重新生成我的API有很多原因(比如,添加/优化MyTaskTypeFromSwagger类,或者完全跳过检查git生成的代码),如果我必须手工编辑生成的API代码,那么所有这些每次重新生成时,编辑都会被吹走.

当然,我可以用例如一个简单的语法编写脚本.pyparsing; 虽然这是我第一次遇到这个问题,但它似乎已经被广泛解决了!

我在C#中编写了许多API,并使用Swashbuckle创建了一个"Swagger"文档网站.

对于Authenticate REST调用,我在标头中使用API​​ Key.

我创建了一个页面,允许下载任何编程语言的特定客户端,如下所示:https://generator.swagger.io

我想让用户使用自己的API密钥生成客户端,这样他就不需要再在代码中手动设置API密钥了.

在我的Swagger JSON中,我有这个安全性定义:

"securityDefinitions": {
    "apiKey": {
        "type": "apiKey",
        "description": "API Key Authentication",
        "name": "X-ApiKey",
        "in": "header"
    }
}

在Swagger Client Generator的页面中,我发现这个模型允许设置客户端选项,但我无法找到客户端代码中API密钥如何(以及是否)可以硬编码(或任何其他类型的授权).

GeneratorInput {
    spec (object, optional),
    options (object, optional),
    swaggerUrl (string, optional),
    authorizationValue (AuthorizationValue, optional),
    securityDefinition (SecuritySchemeDefinition, optional)
}
AuthorizationValue {
    value (string, optional),
    type (string, optional),
    keyName (string, optional)
}
SecuritySchemeDefinition {
    description (string, optional),
    type (string, optional)
}

我想我必须设置AuthorizationValue对象,但没有关于它的文档(或者我找不到它).

能够让生成的客户端lib为所有请求添加任意HTTP头就足够了.

在这种情况下,我们可以添加:

X-ApiKey:{whatever the key is}

有人有想法吗？

非常感谢!

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的一个分支,所以现在也提到了这一点.

我正在玩我的jersey2休息服务.为了更好地概述给定的服务(描述,类型等),我大量使用了swagger(swagger-jersey2-jaxrs).所以我能够创建我的服务描述(swagger.json),我可以通过swagger ui来查看和探索它们.

现在,我需要创建一些客户端来使用这些服务.我来了accrooss swagger codegen cli这是一个很好的工具来生成你的客户端和许多不同的语言(在我的情况下为java).我能够生成api客户端和正在使用的模型.

在这里,我遇到了第一个问题.REST服务和swagger描述是http基本身份验证保护.我阅读了文档 ,它给了我一些暗示,有可能使用基本的auth.在这一点上,我不得不提到,从我的观点来看,doucmentation非常差.它说:

-a, - auth在远程获取swagger定义时添加授权标头.传入URL编码的name:header字符串,并用逗号分隔多个值.

我首先要做的是传递一个字符串,就像在http标题中,但这不起作用甚至谷歌搜索如何使用基本的auth与swagger cli没有导致一些明确的答案.经过大量的尝试和错误后我(我使用CLI 2.1.2)我最终得到了正确的格式,例如:

java -jar swagger-codegen-cli-2.1.2.jar generate -a"授权:基本YWRtaW46YWRtaW4 =" - i http:// localhost:8080/webproject/restapi/swagger.json -l java -o restclient

其中YWRtaW46YWRtaW4 =是我的情况下admin:admin的base64编码值.

到现在为止还挺好.生成的Java客户端也必须使用基本身份验证.我看了一下ApiClient中的方法,发现了setUsername和setPassword.我认为这种方法使客户端能够使用基本身份验证,但没有运气.

所以我深入研究了生成的类,特别是ApiClient和几个生成的ApiService类.我发现setUsername和setPassword没有效果,原因如下:

/**
   * Helper method to set username for the first HTTP basic authentication.
   */
  public void setUsername(String username) {
    for (Authentication auth : authentications.values()) {
      if (auth instanceof HttpBasicAuth) {
        ((HttpBasicAuth) auth).setUsername(username);
        return;
      }
    }
    throw new RuntimeException("No HTTP basic authentication configured!");
  }

同时HashMap定义如下:

// Setup authentications …