Question

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

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

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

我并不害怕搞乱现有的代码，但我想知道是否有人有类似的经验。

目标是使用Swagger UI显示漂亮的文档，并为用户提供调用Apis的操场。

Answer 1

根据上述评论，使用Swagger描述这种API是不可能的。 Swagger规范适用于基于REST的API，其中URL用作描述操作的唯一端点，而不是有效负载。

根据定义，Swagger将唯一操作视为URL和HTTP方法的组合（例如，有些请求扩展定义以包含mime类型，但目前不可用）。 / p>

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

可以成为您未来要求的解决方案，但不是在不久的将来，它不会完全满足您的要求。

要清楚 - 这不是乱码或任何东西的问题。规范本身并不支持它。

Answer 2

要使swagger文件适用于任何通用手工构建的RPC应用程序，需要进行2次简单的调整。

第一个调整是使swagger端点看起来是唯一的。这是通过在上下文中的散列之后使用唯一名称定义每个端点来完成的。这是有效的，因为您的应用不会处理过去的网址＃＆＃39;＃＆＃39;这允许招摇的人认为路径是独特的＃34;。实际上，虽然这种技术将允许swagger文件中定义的每个唯一路径实际调用相同的端点。


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

需要进行其他调整以确保生成的swagger客户端实际上在RPC应用程序内调用正确的操作。这是通过实施＆＃34;默认单值＆＃34;枚举每个命令的请求对象。定义的枚举表示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
   ...

在上面的例子中，属性＆＃34; rest_call＆＃34;是我的底层系统用于将请求分派给正确的底层操作的东西。 myUniqueCommandA的请求对象将其rest_call属性定义为enum [＆＃34; myUniqueCommandA＆＃34;]。 myUniqueCommandB的请求对象将其rest_call属性定义为enum [＆＃34; myUniqueCommandB＆＃34;]。
由于这些枚举定义为默认为同一值的单个值枚举，因此调用这些api的生成的swagger类将被连线以自动传递其正确的路由值。

Swagger API集成非标准Java技术

2 个答案: