Springfox: 在模型中添加对操作等渲染示例的支持。

我只是偶然发现了这个问题。 对我来说，它看起来不仅仅是一个错误而不是一个功能，因为 springfox 支持来自 ApiModel 注释的示例值。 为什么忽略 ApiParam 示例属性？ 是否有我不明白的复杂性？ 如果没有，并且它没有被优先考虑，我会试一试并提供一个小的拉取请求。

那很好啊！ :metal: 如果您有任何问题，请告诉我

+1
到目前为止，有人在这个问题上取得了一些进展吗？
我们也很想拥有这个功能。

目前没有带宽可以做到这一点。 您可能想尝试一下 PR 吗？ 我很乐意帮助回答任何问题。

可悲的是我现在没有时间看这个

+1

有关如何执行此操作的说明，以防有人想提供帮助

嘿，看看这些说明以支持参数的自定义注释。 本质上，我们需要做类似的事情……多做一点工作。

1. 我们需要向Parameter对象添加一个示例属性
2. 给ParameterBuilder添加相应的属性
3. 添加逻辑以将内部Parameter模型映射到 swagger Parameter模型

我们也需要对Response模型做同样的事情。 更新构建器和映射器

完成上述操作后，我们可以为参数创建ParameterBuilderPlugin并为响应示例创建OperationBuilderPlugin插件。

+1

+1

@dilipkrish我有一个关于类似用例的问题。

我有一个可重用的核心 JSON 类（只是 ID/标签对），称为 BasicJSON

用于 POST/PUT/GET（称为 FooJSON）的 JSON 对象具有多个 BasicJSON 类型的字段

我不需要/不想注释各种控制器方法的@ApiParameter或@RequestBody ，我只想为FooJSON 上的不同字段提供BasicJSON 的不同示例。

@ApiModelProperty的示例属性只允许使用字符串。 有没有办法格式化“字符串”值，以便通过swagger ui将其转换为正确的json？ 我尝试了类似 '{"id": 7, value: "Hello"}' 的各种版本的引用，但 UI 将它们视为字符串而不是 json 对象。 在我看来， @ExampleProperty在这种情况下也可能有用，如果示例属性是字符串的硬约束。

是的，您对ExampleProperty看法是正确的。 然而，随着 3.0 的所有这些在不久的将来发生变化，我真的不知道是否值得在核心产品中添加支持，只是很快就会改变它。

感谢您的回复。 3.0 的时间线和功能集是否记录在某处？

一切都在问题队列中......按需求优先排序:) 大多数标记someday故事并不真正值得（我花时间）在核心库中支持，因为已经有可扩展性机制支持它。

抱歉，慢了，你指的是 Springfox 3.0 还是 Swagger 3？ 对于 springfox，我只看到 2.7.0 即将推出。 在这两种情况下，我是否可以通过@ApiModelProperty或类似方式提供更具体的字段示例？

这可能会令人困惑:)

1. OpenAPI是版本 => 2.0（当前）的规范（又名 swagger）。 3.0 在文档结构上有很多新的东西和变化。
2. Swagger-Core是构建在 Open API 2.0 和 JAX-RS、Jersey 以及大量其他 JVM 库和框架之上的工具链。 当前版本 => 1.5.x。 出于所有实际目的，我们不关心这个库。
3. SpringFox是可以为 spring 生态系统生成 OpenAPI 文档（支持 1.2 和 2.0）的库。 当前版本 => 2.7.0-SNAPSHOT

所以我的意思是，由于 (1) 在不久的将来会发生变化，因此在 Springfox (3) 中为 (1) 的 v2.0 构建一些东西并不是很好的利用时间，因为它需要很快重新工作.

那有帮助吗？

谢谢你的清晰👍

我有一个疑问是 Swagger/OpenAPI 版本 3 现在只是一个候选版本，因此 IMO 可能需要一段时间才能获得 Swagger 2 现在拥有的广泛工具支持和社区的接受。 此外，由于 springfox 仍然支持 Swagger 1，我无法想象 springfox 会很快放弃对 swagger 2 的支持:) 因此，即使实现细节会因 swagger 2 与一个 swagger 3 案卷。

OTOH，我意识到在springfox中支持OpenAPI 3.0.0的努力自然会出现在这种功能请求之前。 非常感谢你为这个项目所做的一切！

注意：这里我使用 swagger 来粗略地表示 OpenAPI

实际上，在规范的版本之间移动要容易得多，理解 springs 模型的艰苦工作已经完成。 swagger1/swagger2 只是我们创建的内部模型的一个项目。 即我们有自己的模型 => swagger1 映射层 == 产生 ==> swagger1
和 swagger2 相同。

现在我们的内部模型有点偏差，因为它们曾经反映了 swagger 1，我们已经越来越多地添加它以暴露新的概念，例如示例。

swagger 3 的结构与它的前辈有点不同，所以我不确定改变内部模型需要付出的努力。 作品中有很多新概念如链接/超媒体，更丰富的模式支持如 allOf 和 anyOf，更丰富的示例支持。 因此，在我了解它的影响之前，我不想投入大量精力来支持/改进模型以处理示例等。 真的，一旦它在那里就必须得到支持:)

+1

需要支持，例如 Springfox
{ @ApiImplicitParam(example = "...") } 使用 Sprinfox 不起作用。

+1

+1

+1

+1

+1

+1

+1

+1

+1

@dilipkrish您之前评论说，工作是根据需求从问题队列中优先考虑的。 似乎对解决这个问题有很高的兴趣，所以我想知道这项工作是否仍然优先于支持 OpenAPI 3.0

+1

@andrew-garland 不幸的是，我最近没有太多时间。 这就是为什么我依赖外部贡献looking-for-contributions 。 首要任务是获得 OAS 3.0 支持。

+1

+1

+1

欢迎大家踊跃投稿

+1

+1

+1

+1

+1

+1

+1

+1

+1

+1

+1

+1

+1

@JensSchliesser +1 是为了什么？ 它已经实施。

+1 感谢您的实施

是否有这样的工作示例，因为我无法在 swagger ui 中工作和显示示例内容，并且我尝试使用 2.9.0

+1 真的需要它

@darrellme 文档中有一个示例，对于标量属性，请执行此操作。

+1

+1

@dilipkrish您的示例生成带有对象示例的“x-examples”字段。 但是 SwaggerUI 3.x 不支持“x-examples”。 是否有复杂对象示例的工作示例？ 谢谢

我不确定它是否在 ui 中受支持

@darrellme 文档中有一个示例，对于标量属性，请执行此操作。

@dilipkrish它也适用于RequestBody吗？ 我没有看到任何相同的例子。
尝试使用 SpringFox 2.9.2，以下代码供参考：
@ApiParam(name = "body",value = "Request body in JSON format...",required=true, examples = @io.swagger.annotations.Example(value= @ExampleProperty( mediaType = MediaType.APPLICATION_JSON_VALUE, value = "{foo: whatever, bar: whatever2}")) ) <strong i="14">@RequestBody</strong> String body,

我想显示一个大的 JSON 作为请求正文的示例值，单击“试用”应用程序应该在编辑模式下显示相同。 请参考以下 URL 了解我的期望行为 [] https://petstore.swagger.io/#/store/placeOrder
另请注意，我没有将参数中的任何对象传递给方法，它是简单的“字符串”类型请求主体，正如我在上面的代码片段中提到的那样。
请建议。

目前没有带宽可以做到这一点。 您可能想尝试一下 PR 吗？ 我很乐意帮助回答任何问题。

有关如何执行此操作的说明，以防有人想提供帮助

嘿，看看这些说明以支持参数的自定义注释。 本质上，我们需要做类似的事情……多做一点工作。

1. 我们需要向Parameter对象添加一个示例属性
2. 给ParameterBuilder添加相应的属性
3. 添加逻辑以将内部Parameter模型映射到 swagger Parameter模型

我们也需要对Response模型做同样的事情。 更新构建器和映射器

完成上述操作后，我们可以为参数创建ParameterBuilderPlugin并为响应示例创建OperationBuilderPlugin插件。
嗨，我在使用 Swagger 时遇到问题。控制器方法中的响应主体有一个映射。
那么我如何描述我的响应正文中的每个字段，以便其他人可以理解。
目前，响应示例没什么，你能给出一个演示来实现它吗？

有关如何执行此操作的说明，以防有人想提供帮助

嘿，看看这些说明以支持参数的自定义注释。 本质上，我们需要做类似的事情……多做一点工作。

1. 我们需要向Parameter对象添加一个示例属性
2. 给ParameterBuilder添加相应的属性
3. 添加逻辑以将内部Parameter模型映射到 swagger Parameter模型

我们也需要对Response模型做同样的事情。 更新构建器和映射器

完成上述操作后，我们可以为参数创建ParameterBuilderPlugin并为响应示例创建OperationBuilderPlugin插件。
@dilipkrish
嗨，我在使用 Swagger 时遇到问题。控制器方法中的响应主体有一个映射。
那么我如何描述我的响应正文中的每个字段，以便其他人可以理解。
目前，响应示例没什么，你能给出一个演示来实现它吗？