Apicurio-studio: Urutan jalur di yml API tidak diurutkan dan tidak cocok dengan jalur di UI

Dibuat pada 12 Mar 2019  ·  5Komentar  ·  Sumber: Apicurio/apicurio-studio

Halo,

Saya tidak tahu apakah ini bug atau en enhancement, tapi ini dia

Deskripsi masalah

Katakanlah saya ingin membuat API dengan empat jalur:

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

Tapi mari kita pertimbangkan saya memasukkannya menggunakan UI dalam urutan khusus ini:

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

UI bagus dan jalurnya tampak diurutkan, cocok dengan yang saya inginkan:

image

Tapi, yml yang dihasilkan tidak berurutan dan tidak cocok dengan apa yang muncul di UI:

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

Biasanya, saya tidak akan terlalu peduli dengan urutan jalur dalam file yml mentah
Tetapi masalahnya adalah ReDoc mengikuti urutan jalur di yml

Jadi dokumentasi yang dihasilkan tidak dipesan:

image

image

Ini adalah masalah karena begitu API mulai aktif, beberapa jalur diperbarui, beberapa dihapus, dan beberapa dibuat
Ini berarti bahwa dokumentasi yang dihasilkan dengan cepat menjadi kacau balau

Apa yang bisa dilakukan

Saya punya beberapa ide, itu jauh dari sempurna tapi ini permulaan
Mungkin kita bisa membangunnya dan menguraikannya

  • Selalu urutkan API yang dihasilkan
    Kelebihan: Mudah diterapkan (menurut saya?)
    Cons: Pengguna tidak dapat memilih pesanan mereka sendiri
  • Tambahkan opsi untuk mengurutkan jalur di API yang dihasilkan
    Kelebihan: Mudah diterapkan (menurut saya?)
    Kontra: Pengguna tidak dapat mengubah urutan jalur individu
  • Ubah UI agar jalur yang ditampilkan tidak berurutan,
    dan tambahkan tombol untuk mengurutkan semuanya + tombol untuk memindahkan masing-masing jalur ke atas dan ke bawah
    Kelebihan: Akan menyelesaikan segalanya
    Cons: Paling sulit untuk diterapkan (saya pikir?)
enhancement

Komentar yang paling membantu

Saya mengalami masalah ini juga; pengamatan saya tentang ini adalah bahwa APICURIO hanya menambahkan definisi baru ke YAML saat ini baik saat kita membuat jalur baru; atau ketika kita benar-benar mengganti yaml (misalnya untuk jalur individual jika saya memodifikasi sesuatu dari tab 'sumber').

Saya secara manual memanipulasi basis data untuk memperbaikinya setelah saya memodifikasi YAML sendiri (kemudian memperbarui kolom), dan entah bagaimana semuanya rusak sehingga saya harus menghapus proyek dan memulai kembali.

Seperti yang dikatakan @EricWittmann , saya pikir yang terbaik adalah mengurutkan jalur dan daftar lain sebelum menyerahkan konten ke ReDoc, atau kita dapat menggunakan tombol lain di tab 'sumber' di sebelah tombol 'Format' (mungkin dinamai sebagai 'Urutkan Jalur'), yang bisa kita tangani sendiri.

Semua 5 komentar

Ups, maaf, saya lupa melampirkan YML yang saya gunakan untuk tangkapan layar ReDoc
(Yang saya tempel tidak memiliki operasi, jadi ReDoc menghasilkan dokumen kosong)

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'

Ini adalah masalah menarik yang secara mengejutkan belum pernah muncul sebelumnya! Sebenarnya ada beberapa tempat di UI di mana saya pikir kami harus menyediakan opsi C Anda - menampilkan item dalam urutan yang muncul di dokumen tetapi menawarkan opsi untuk mengurutkan dan mengurutkan ulang (seret dan lepas, mungkin).

Yang mengatakan, solusi sementara adalah mengurutkan jalur dan daftar lain sebelum menyerahkan konten ke ReDoc. Itu akan cepat dan mudah dilakukan dan akan memperbaiki masalah spesifik dari fitur "Pratinjau" Apicurio.

Adakah pemikiran/ide tentang ini, @jsenko ?

Saya mengalami masalah ini juga; pengamatan saya tentang ini adalah bahwa APICURIO hanya menambahkan definisi baru ke YAML saat ini baik saat kita membuat jalur baru; atau ketika kita benar-benar mengganti yaml (misalnya untuk jalur individual jika saya memodifikasi sesuatu dari tab 'sumber').

Saya secara manual memanipulasi basis data untuk memperbaikinya setelah saya memodifikasi YAML sendiri (kemudian memperbarui kolom), dan entah bagaimana semuanya rusak sehingga saya harus menghapus proyek dan memulai kembali.

Seperti yang dikatakan @EricWittmann , saya pikir yang terbaik adalah mengurutkan jalur dan daftar lain sebelum menyerahkan konten ke ReDoc, atau kita dapat menggunakan tombol lain di tab 'sumber' di sebelah tombol 'Format' (mungkin dinamai sebagai 'Urutkan Jalur'), yang bisa kita tangani sendiri.

Seperti #394, saya pikir ide umum di sini adalah bahwa UI Apicurio harus sesuai dengan urutan YAML untuk semua jenis elemen (jalur, bidang, mungkin tipe data) karena urutan itu terkadang penting (seperti untuk membuat dokumentasi).

Satu hal sederhana yang akan membantu di sini adalah mengaktifkan tombol Simpan saat mengedit YAML mentah dan hanya mengubah urutan elemen. Saat ini, Apicurio agak terlalu pintar dan menghilangkan tombol Simpan ketika satu-satunya hal yang berubah adalah urutan elemennya.

Saya pikir hal terbaik adalah memesan di UI agar sesuai dengan sumbernya (seperti yang disebutkan) dan bagi pengguna untuk dapat memindahkan barang-barang melalui drag & drop. Itu bukan perubahan sepele tetapi hal yang benar untuk dilakukan IMO. Pikiran @jsenko ?

Apakah halaman ini membantu?
0 / 5 - 0 peringkat