Apicurio-studio: yml API中的路径顺序无序,与UI中的路径不匹配

创建于 2019-03-12  ·  5评论  ·  资料来源: Apicurio/apicurio-studio

你好,

我不知道这是错误还是增强功能,但在这里

问题说明

假设我想创建一个具有四个路径的 API:

  • POST /bar
  • GET /bar/{id_bar}
  • POST /foo
  • GET /foo/{id_foo}

但是让我们考虑一下我以这个特定的顺序使用 UI 插入它们:

  • GET /foo/{id_foo}
  • POST /bar
  • GET /bar/{id_bar}
  • POST /foo

用户界面很好,路径显示排序,符合我想要的:

image

但是,生成的 yml 没有排序,并且与 UI 中显示的内容不匹配:

openapi: 3.0.2
info:
    title: 'Test API'
    version: 1.0.0
paths:
    '/foo/{id_foo}': {}
    /bar: {}
    '/bar/{id_bar}': {}
    /foo: {}

通常,我不会真正关心原始 yml 文件中路径的顺序
但问题是ReDoc 遵循 yml 中路径的顺序

所以生成的文档没有排序:

image

image

这是一个问题,因为一旦 API 开始存在,一些路径会更新,一些会被删除,一些会被创建
这意味着生成的文档很快就会变成乱码

可以做什么

我有一些想法,它们远非完美,但这是一个开始
也许我们可以在它们的基础上进一步阐述

  • 始终对输出的 API 进行排序
    优点:易于实施(我认为?)
    缺点:用户无法选择自己的订单
  • 添加选项以对输出 API 中的路径进行排序
    优点:易于实施(我认为?)
    缺点:用户无法更改各个路径的顺序
  • 修改 UI 使显示的路径不排序,
    并添加一个按钮来对所有内容进行排序+按钮来上下移动各个路径
    优点:可以解决一切
    缺点:最难实施(我认为?)
enhancement

最有用的评论

我也遇到了这个问题; 我对此的观察是,APICURIO 只是在我们创建新路径时将新定义附加到当前 YAML 中; 或者当我们完全替换 yaml 时(例如,如果我从“源”选项卡修改某些内容,则用于单个路径)。

在我自己修改 YAML(然后更新列)之后,我手动操作数据库来修复这个问题,并且以某种方式破坏了我必须删除项目并重新启动的所有内容。

正如@EricWittmann所说,我认为最好在将内容交给 ReDoc 之前对路径和其他列表进行排序,或者我们可以在“格式”按钮旁边的“源”选项卡中使用另一个按钮(可能命名为“排序路径”),我们可以自己处理。

所有5条评论

糟糕,抱歉,我忘了附上我用于 ReDoc 截图的 YML
(我贴的没有操作,所以ReDoc生成一个空doc)

openapi: 3.0.2
info:
    title: 'Test API'
    version: 1.0.0
paths:
    '/foo/{id_foo}':
        get:
            summary: 'Obtain a foo'
            parameters:
                -
                    name: id_foo
                    in: path
                    required: true
                    schema:
                        type: number
            responses:
                '201':
                    description: 'A foo'
    /bar:
        post:
            summary: 'Create a bar'
            responses:
                '200':
                    description: 'A bar'
    '/bar/{id_bar}':
        get:
            summary: 'Obtain a bar'
            parameters:
                -
                    name: id_bar
                    in: path
                    required: true
                    schema:
                        type: number
            responses:
                '201':
                    description: 'Bar created'
    /foo:
        post:
            summary: 'Create a foo'
            responses:
                '200':
                    description: 'Foo created'

这是一个有趣的问题,令人惊讶的是以前没有出现过! 实际上,我认为 UI 中有几个地方应该提供您的选项 C - 按照它们在文档中出现的顺序显示项目,但提供排序和重新排序的选项(大概是拖放)。

也就是说,临时解决方案是在将内容交给 ReDoc之前对路径和其他列表进行排序。 这将是快速且容易做到的,并且可以解决 Apicurio“预览”功能的特定问题。

对此有什么想法/想法, @jsenko

我也遇到了这个问题; 我对此的观察是,APICURIO 只是在我们创建新路径时将新定义附加到当前 YAML 中; 或者当我们完全替换 yaml 时(例如,如果我从“源”选项卡修改某些内容,则用于单个路径)。

在我自己修改 YAML(然后更新列)之后,我手动操作数据库来修复这个问题,并且以某种方式破坏了我必须删除项目并重新启动的所有内容。

正如@EricWittmann所说,我认为最好在将内容交给 ReDoc 之前对路径和其他列表进行排序,或者我们可以在“格式”按钮旁边的“源”选项卡中使用另一个按钮(可能命名为“排序路径”),我们可以自己处理。

像 #394 一样,我认为这里的总体思路是 Apicurio UI 应该与所有类型元素(路径、字段,可能是数据类型)的 YAML 排序相对应,因为该顺序有时很重要(例如生成文档)。

在这里有用的一件简单的事情是在编辑原始 YAML 并仅更改元素的顺序时启用“保存”按钮。 目前,Apicurio 有点太聪明了,当唯一改变的是元素的顺序时,保存按钮会变灰。

我认为最好的办法是在 UI 中进行排序以匹配源(如前所述),并且让用户能够通过拖放来移动内容。 这不是一个微不足道的改变,而是做 IMO 的正确做法。 想法@jsenko

此页面是否有帮助?
0 / 5 - 0 等级