带有嵌套子资源文档的OpenApi文档工具

时间:2020-07-29 21:15:45

标签: swagger postman swagger-ui openapi

我们当前正在使用swagger-ui来为Rest-API生成文档。但是,由于我们有很多API,并且我们的API是使用嵌套的子资源表示形式进行编码的,因此swagger-ui看起来并不令人满意。看起来很混乱。

例如,我有以下端点

  1. / v1 /员工/地址
  2. / v1 /员工/联系人
  3. / v1 /雇主/地址
  4. / v1 / employer / contacts

当前,我的swagger-ui会生成这样的文档。

POST / v1 /员工/地址

PUT / v1 /员工/地址/ {address_id}

删除/ v1 /员工/地址{address_id}

POST / v1 /员工/联系人

PUT / v1 /员工/联系人{contact_id}

删除/ v1 /员工/联系人{contact_id}

POST / v1 /雇主/地址

PUT / v1 /雇主/地址{address_id}

删除/ v1 /雇主/地址{address_id}

POST / v1 /雇主/联系人

PUT / v1 /雇主/联系人{contact_id}

删除/ v1 / employer / contacts {contact_id}

我知道我们可以应用标签来进一步对API进行分组。但是我也真的不喜欢。我们有10000多个API端点。即使应用了标签,它也看起来一团糟。

我需要像这样嵌套文档。

  • v1
    • 员工
      • 地址
        • POST创建地址
        • PUT更新地址
        • 删除删除地址
      • 联系人
        • POST创建联系人
        • PUT更新联系人
        • 删除删除联系人
    • 雇主
      • 地址
        • POST创建地址
        • PUT更新地址
        • 删除删除地址
      • 联系人
        • POST创建联系人
        • PUT更新联系人
        • 删除删除联系人

当前Postman文档支持嵌套资源表示。 Postman doc。但是邮递员还有其他限制,这使我不想使用它。例如,它不支持文档的私人共享。

然后是miredot。但是它不支持OpenApi规范。

有没有办法实现这种swagger-ui?

0 个答案:

没有答案