Halo,
Saya tidak tahu apakah ini bug atau en enhancement, tapi ini dia
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:
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:
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
Saya punya beberapa ide, itu jauh dari sempurna tapi ini permulaan
Mungkin kita bisa membangunnya dan menguraikannya
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 ?
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.