我们有一个使用带有JSON的http POST作为RPC方法的系统 . 它是内部组件通信的内部解决方案 .
请求和响应分别由Java bean(POJO)描述 .
我的问题是,如何使用swagger注释在swagger标准中创建好的文档?
我并不害怕搞乱现有的代码,但我想知道是否有人有类似的经验 .
目标是使用Swagger UI显示漂亮的文档,并为用户提供调用Apis的操场 .
根据上面的评论,使用Swagger描述这种API是不可能的 . Swagger规范适用于基于REST的API,其中URL充当描述操作的唯一 endpoints ,而不是有效负载 .
根据定义,Swagger将唯一操作视为URL和HTTP方法的组合(例如,有些请求扩展定义以包含mime类型,但它目前不可用) .
根本没有办法描述操作多个请求类型的单个 endpoints ,每个 endpoints 都有自己的输出 .
对于您将来要求的内容,可能会有一个解决方案,但不是在不久的将来,它不会完全满足您的要求 .
要清楚 - 这不是乱码或任何东西的问题 . 规范本身不支持它 .
对于任何通用手工构建的RPC应用程序,都需要进行2次简单调整才能使swagger文件正常工作 .
第一个调整是使swagger endpoints 看起来是唯一的 . 这是通过在上下文中的散列之后使用唯一名称定义每个 endpoints 来完成的 . 这是有效的,因为您的应用程序不会处理超过“#”的网址,这允许swagger将路径视为“唯一” . 实际上,虽然这种技术将允许swagger文件中定义的每个唯一路径实际调用相同的 endpoints .
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类将被连线以自动传递其正确的路由值 .
2 回答
根据上面的评论,使用Swagger描述这种API是不可能的 . Swagger规范适用于基于REST的API,其中URL充当描述操作的唯一 endpoints ,而不是有效负载 .
根据定义,Swagger将唯一操作视为URL和HTTP方法的组合(例如,有些请求扩展定义以包含mime类型,但它目前不可用) .
根本没有办法描述操作多个请求类型的单个 endpoints ,每个 endpoints 都有自己的输出 .
对于您将来要求的内容,可能会有一个解决方案,但不是在不久的将来,它不会完全满足您的要求 .
要清楚 - 这不是乱码或任何东西的问题 . 规范本身不支持它 .
对于任何通用手工构建的RPC应用程序,都需要进行2次简单调整才能使swagger文件正常工作 .
第一个调整是使swagger endpoints 看起来是唯一的 . 这是通过在上下文中的散列之后使用唯一名称定义每个 endpoints 来完成的 . 这是有效的,因为您的应用程序不会处理超过“#”的网址,这允许swagger将路径视为“唯一” . 实际上,虽然这种技术将允许swagger文件中定义的每个唯一路径实际调用相同的 endpoints .
需要进行另一个调整以确保生成的swagger客户端实际上在RPC应用程序内调用正确的操作 . 这是通过在每个命令的请求对象中实现“默认单值”枚举来完成的 . 定义的枚举表示api需要传递的相应属性/值组合,以便分派到应用程序内的正确目标操作:
在上面的示例中,属性"rest_call"是我的底层系统用于将请求分派给正确的底层操作的属性 . myUniqueCommandA的请求对象将其rest_call属性定义为enum ["myUniqueCommandA"] . myUniqueCommandB的请求对象将其rest_call属性定义为enum ["myUniqueCommandB"] .
由于这些枚举定义为单个值枚举,这些枚举也默认为相同的值,因此生成的调用这些api的swagger类将被连线以自动传递其正确的路由值 .