Apicurio-studio: yml APIのパスの順序が順序付けられておらず、UIのパスと一致していません

作成日 2019年03月12日  ·  5コメント  ·  ソース: Apicurio/apicurio-studio

こんにちは、

これがバグなのか拡張版なのかはわかりませんが、ここにあります

この件についての説明

次の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は素晴らしく、パスはソートされて表示され、私が望むものと一致します。

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は空のドキュメントを生成します)

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を考えますか?

このページは役に立ちましたか?
0 / 5 - 0 評価