用于非标准 Java 技术的 Swagger API 集成

Question

我们有一个使用带有JSON的http POST作为RPC方法的系统。它是内部组件通信的内部解决方案。

请求和响应分别由 Java Bean （POJO） 描述。

我的问题是，如何使用大摇大摆的注释在大摇大摆的标准中创建漂亮的文档？

我不怕弄乱现有代码，但我想知道是否有人对类似的东西有一些经验。

目标是使用 Swagger UI 来显示漂亮的文档，并为用户提供调用 API 的游乐场。

Answer 1

根据上面的评论，不可能使用 Swagger 来描述这种 API。Swagger 规范旨在用于基于 REST 的 API，其中 URL 充当描述操作的唯一终结点，而不是有效负载。

根据定义，Swagger 认为唯一操作是 URL 和 HTTP 方法的组合（例如，有人请求扩展定义以包括 mime 类型，但目前不可用）。

根本无法描述操作多个请求类型的单个终结点，每个请求类型都有自己的输出。

将来可能会有针对您要求的解决方案，但它不会在不久的将来，也不会充分满足您的要求。

需要明确的是 - 这不是弄乱代码或任何东西的问题。规范本身不支持它。

Answer 2

需要 2 个简单的调整才能使 swagger 文件适用于任何通用的手动构建的 RPC 应用程序。

第一个调整是使招摇端点看起来是唯一的。这是通过在上下文中的哈希之后使用唯一名称定义每个终结点来完成的。这是有效的，因为你的应用不会处理超过"#"的网址，这允许 swagger 认为路径是"唯一的"。实际上，这种技术将允许 swagger 文件中定义的每个唯一路径实际调用相同的端点。

  paths:
    /endpoint#myUniqueCommandA
      ...
    /endpoint#myUniqueCommandB
      ...

需要进行另一项调整，以确保生成的 swagger 客户端将在 RPC 应用中实际调用正确的操作。这是通过在每个命令的请求对象中实现"默认单值"枚举来完成的。定义的枚举表示 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属性定义为 enum["myUniqueCommandA"]。myUniqueCommandB 的请求对象将其rest_call属性定义为 enum["myUniqueCommandB"]。
由于这些被定义为也默认为相同值的单个值枚举，因此调用这些 API 的生成的 swagger 类将被连接以自动传递其正确的路由值。