首页 文章

Swagger API集成非标准Java技术

提问于
浏览
0

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

请求和响应分别由Java bean(POJO)描述 .

我的问题是,如何使用swagger注释在swagger标准中创建好的文档?

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

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

2 回答

  • 1

    根据上面的评论,使用Swagger描述这种API是不可能的 . Swagger规范适用于基于REST的API,其中URL充当描述操作的唯一 endpoints ,而不是有效负载 .

    根据定义,Swagger将唯一操作视为URL和HTTP方法的组合(例如,有些请求扩展定义以包含mime类型,但它目前不可用) .

    根本没有办法描述操作多个请求类型的单个 endpoints ,每个 endpoints 都有自己的输出 .

    对于您将来要求的内容,可能会有一个解决方案,但不是在不久的将来,它不会完全满足您的要求 .

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

  • 1

    对于任何通用手工构建的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类将被连线以自动传递其正确的路由值 .

相关问题