Swagger API 非标准 Java 技术集成
Swagger API integration for non standard Java technology
我们有一个使用 http POST 和 JSON 作为 RPC 方法的系统。
它是用于内部组件通信的内部解决方案。
请求和响应分别由 Java bean (POJO) 描述。
我的问题是，如何使用 swagger 注释在 swagger 标准中创建漂亮的文档？
我不怕乱用现有代码，但我想知道是否有人对类似的事情有一些经验。
目标是使用 Swagger UI 来显示漂亮的文档并为用户提供一个调用 API 的游乐场。
根据上面的评论，使用 Swagger 无法描述这种 API。 Swagger 规范适用于基于 REST 的 APIs，其中 URLs 用作描述操作的唯一端点，而不是有效负载。
根据定义，Swagger 将独特的操作视为 URL 和 HTTP 方法的组合（例如，有人请求扩展定义以包括 mime 类型，但它是当前不可用）。
根本无法描述操作多个请求类型的单个端点，每个请求类型都有自己的输出。
将来可能可以解决您的要求，但不会在不久的将来，它不会最大限度地满足您的要求。
需要说明的是 - 这不是乱用代码或任何东西的问题。规范本身不支持。
要使 swagger 文件适用于任何通用的手工构建 RPC 应用程序，需要进行 2 项简单的调整。
第一个调整是让 swagger 端点看起来是独一无二的。这是通过在上下文中的哈希后使用唯一名称定义每个端点来完成的。这是可行的，因为您的应用程序不会处理“#”之后的 url，这允许 swagger 将路径视为 "unique"。实际上，虽然这种技术将允许 swagger 文件中定义的每个唯一路径实际调用相同的端点。
paths:
/endpoint#myUniqueCommandA
...
/endpoint#myUniqueCommandB
...
需要进行其他调整以确保生成的 swagger 客户端实际上会在您的 RPC 应用程序中调用正确的操作。这是通过在每个命令的请求对象中实现一个 "defaulted single value" 枚举来完成的。定义的枚举表示 api 需要传递的相应属性/值组合，以便分派到应用程序内的正确目标操作：
...
definitions:
MyUniqueCommandARequest:
type: object
properties:
rest_call:
type: string
enum:
- myUniqueCommandA
default: myUniqueCommandA
...
MyUniqueCommandBRequest:
type: object
properties:
rest_call:
type: string
enum:
- myUniqueCommandB
default: myUniqueCommandB
...
在上面的示例中，属性 "rest_call" 是我的底层系统用来将请求分派到正确的底层操作的。
myUniqueCommandA 的请求对象将其 rest_call 属性定义为枚举 ["myUniqueCommandA"]。 myUniqueCommandB 的请求对象的 rest_call 属性定义为枚举 ["myUniqueCommandB"].
由于这些被定义为也默认为相同值的单个值枚举，因此调用这些 api 的生成的 swagger 类 将被连接以自动传递其正确的路由值。
我们有一个使用 http POST 和 JSON 作为 RPC 方法的系统。 它是用于内部组件通信的内部解决方案。
请求和响应分别由 Java bean (POJO) 描述。
我的问题是，如何使用 swagger 注释在 swagger 标准中创建漂亮的文档？
我不怕乱用现有代码，但我想知道是否有人对类似的事情有一些经验。
目标是使用 Swagger UI 来显示漂亮的文档并为用户提供一个调用 API 的游乐场。
根据上面的评论，使用 Swagger 无法描述这种 API。 Swagger 规范适用于基于 REST 的 APIs，其中 URLs 用作描述操作的唯一端点，而不是有效负载。
根据定义，Swagger 将独特的操作视为 URL 和 HTTP 方法的组合（例如，有人请求扩展定义以包括 mime 类型，但它是当前不可用）。
根本无法描述操作多个请求类型的单个端点，每个请求类型都有自己的输出。
将来可能可以解决您的要求，但不会在不久的将来，它不会最大限度地满足您的要求。
需要说明的是 - 这不是乱用代码或任何东西的问题。规范本身不支持。
要使 swagger 文件适用于任何通用的手工构建 RPC 应用程序，需要进行 2 项简单的调整。
第一个调整是让 swagger 端点看起来是独一无二的。这是通过在上下文中的哈希后使用唯一名称定义每个端点来完成的。这是可行的，因为您的应用程序不会处理“#”之后的 url，这允许 swagger 将路径视为 "unique"。实际上，虽然这种技术将允许 swagger 文件中定义的每个唯一路径实际调用相同的端点。
paths:
/endpoint#myUniqueCommandA
...
/endpoint#myUniqueCommandB
...
需要进行其他调整以确保生成的 swagger 客户端实际上会在您的 RPC 应用程序中调用正确的操作。这是通过在每个命令的请求对象中实现一个 "defaulted single value" 枚举来完成的。定义的枚举表示 api 需要传递的相应属性/值组合，以便分派到应用程序内的正确目标操作：
...
definitions:
MyUniqueCommandARequest:
type: object
properties:
rest_call:
type: string
enum:
- myUniqueCommandA
default: myUniqueCommandA
...
MyUniqueCommandBRequest:
type: object
properties:
rest_call:
type: string
enum:
- myUniqueCommandB
default: myUniqueCommandB
...
在上面的示例中，属性 "rest_call" 是我的底层系统用来将请求分派到正确的底层操作的。
myUniqueCommandA 的请求对象将其 rest_call 属性定义为枚举 ["myUniqueCommandA"]。 myUniqueCommandB 的请求对象的 rest_call 属性定义为枚举 ["myUniqueCommandB"].
由于这些被定义为也默认为相同值的单个值枚举，因此调用这些 api 的生成的 swagger 类 将被连接以自动传递其正确的路由值。