你好,
我不知道这是错误还是增强功能,但在这里
假设我想创建一个具有四个路径的 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
用户界面很好,路径显示排序,符合我想要的:
但是,生成的 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 中路径的顺序
所以生成的文档没有排序:
这是一个问题,因为一旦 API 开始存在,一些路径会更新,一些会被删除,一些会被创建
这意味着生成的文档很快就会变成乱码
我有一些想法,它们远非完美,但这是一个开始
也许我们可以在它们的基础上进一步阐述
糟糕,抱歉,我忘了附上我用于 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 ?
最有用的评论
我也遇到了这个问题; 我对此的观察是,APICURIO 只是在我们创建新路径时将新定义附加到当前 YAML 中; 或者当我们完全替换 yaml 时(例如,如果我从“源”选项卡修改某些内容,则用于单个路径)。
在我自己修改 YAML(然后更新列)之后,我手动操作数据库来修复这个问题,并且以某种方式破坏了我必须删除项目并重新启动的所有内容。
正如@EricWittmann所说,我认为最好在将内容交给 ReDoc 之前对路径和其他列表进行排序,或者我们可以在“格式”按钮旁边的“源”选项卡中使用另一个按钮(可能命名为“排序路径”),我们可以自己处理。