こんにちは、
これがバグなのか拡張版なのかはわかりませんが、ここにあります
次の4つのパスで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
UIは素晴らしく、パスはソートされて表示され、私が望むものと一致します。
ただし、結果の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は空のドキュメントを生成します)
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順序に対応する必要があるということです。これは、その順序が重要な場合があるためです(ドキュメントの生成など)。
ここで役立つ簡単なことの1つは、生のYAMLを編集し、要素の順序だけを変更するときに[保存]ボタンを有効にすることです。 現在、Apicurioは少し賢すぎて、要素の順序だけが変更されている場合は[保存]ボタンがグレー表示になります。
UIで(前述のように)ソースと一致するように順序付けし、ユーザーがドラッグアンドドロップでコンテンツを移動できるようにするのが最善だと思います。 これは些細な変更ではありませんが、IMOを実行するための正しいことです。 @jsenkoを考えますか?
最も参考になるコメント
私もこの問題に遭遇しました。 これに関する私の観察では、APICURIOは、新しいパスを作成するときに、どちらかで現在のYAMLに新しい定義を追加するだけです。 または、yamlを完全に置き換える場合(たとえば、[ソース]タブから何かを変更した場合の個々のパスの場合)。
YAMLを自分で変更した後(次に列を更新した後)、データベースを手動で操作してこれを修正しました。どういうわけか、プロジェクトを削除して再起動する必要があるすべてが壊れました。
@EricWittmannが言ったように、コンテンツをReDocに渡す前にパスやその他のリストを並べ替えるのが最善だと思います。または、[フォーマット]ボタンの横にある[ソース]タブで別のボタンを使用することもできます([パスの並べ替え]という名前を付けることもできます)。自分で処理できること。