Mengonversi JSON spesifikasi Swagger ke dokumentasi HTML

90

Untuk beberapa REST API yang ditulis dalam PHP, saya diminta untuk membuat dokumentasi Swagger , dan karena saya tidak mengetahui cara mudah untuk menambahkan anotasi ke API yang ada tersebut dan membuat dokumentasi seperti itu, saya menggunakan editor ini untuk menghasilkan beberapa untuk saat ini.

Saya menyimpan file JSON dan YAML yang dibuat menggunakan editor itu, dan sekarang saya perlu membuat dokumentasi Swagger interaktif terakhir (pernyataan ini mungkin terdengar naif dan tidak jelas).

Adakah yang bisa memberi tahu saya bagaimana cara mengonversi file spesifikasi Swagger JSON menjadi dokumentasi Swagger yang sebenarnya?

Saya menggunakan platform Windows dan tidak tahu apa-apa tentang Ant / Maven.

yaml swagger swagger-php Salil
sumber
saya mencoba [ github.com/wordnik/swagger-ui](Swagger UI) tetapi tidak merender json saya. satu-satunya peringatan yang ditampilkan adalah "API ini menggunakan versi Swagger yang sudah tidak digunakan lagi! Silakan lihat github.com/wordnik/swagger-core/wiki untuk info lebih lanjut".
Salil

Jawaban:

43

Saya tidak puas dengan swagger-codegensaat saya mencari alat untuk melakukan ini, jadi saya menulis sendiri. Lihat bootprint-swagger

Tujuan utama dibandingkan swagger-codegenadalah untuk menyediakan pengaturan yang mudah (meskipun Anda memerlukan nodejs). Dan seharusnya mudah untuk menyesuaikan gaya dan template dengan kebutuhan Anda sendiri, yang merupakan fungsionalitas inti dari bootprint -project

Nils Knappmeier
sumber
9
Peringatan: Pada 11/2016, penulis bootprint-swagger tampaknya telah meninggalkan proyek tersebut. swagger-codegen masih didukung dengan baik.
Brent Matzelle
22
Saya adalah penulisnya dan teksnya berbunyi: "Saya menyesal mengatakan bahwa saya tidak dapat mengembangkan fitur baru untuk proyek ini dalam waktu dekat. Tetapi: Saya mungkin akan dapat mendiskusikan dan menggabungkan permintaan tarik, dan untuk menerbitkan versi baru. " Anda mungkin menyebutnya ditinggalkan, saya akan menyebutnya "ditahan". Saya juga akan mengundang siapa saja yang tertarik untuk berkontribusi dalam proyek ini.
Nils Knappmeier
1
Ditemukan yang spectaclemenghasilkan dokumentasi yang jauh lebih baik dari JSON yang angkuh
eternalthinker
61

Coba gunakan redoc-cli .

Saya menggunakan bootprint-openapi oleh yang saya menghasilkan banyak file ( bundle.js, bundle.js.map, index.html, main.cssdan main.css.map) dan kemudian Anda dapat mengubahnya menjadi satu .htmlfile menggunakan html-inline untuk menghasilkan sederhana index.htmlberkas.

Kemudian saya menemukan redoc-cli sangat mudah digunakan dan hasilnya benar-benar-2 mengagumkan, satu file index.html dan indah .

Instalasi :

npm install -g redoc-cli

Penggunaan :

redoc-cli bundle -o index.html swagger.json
Vikasdeep Singh
sumber
8
Alat ini benar-benar menghasilkan keluaran paling indah dari semua alat yang disebutkan.
Jakub Moravec
File HTML all-in-one yang dihasilkan cukup besar. Begitu juga dengan ketergantungan pustaka JS (~ 800KB) dalam hal rendering langsung dari HTML khusus. Adakah yang tahu bagaimana ukurannya bisa diperkecil?
aaronqli
1
Sejauh ini yang ini adalah yang terbaik, dan karena kami membuat ini untuk pengembang yang menggunakan desktop, ukuran output tidak menjadi masalah.
milosmns
3
Menggunakan nama yang dapat dieksekusi langsung tidak selalu berfungsi, eksekusi oleh npx redoc-cli ...lebih bisa diandalkan.
Crouching Kitten
21

Semuanya terlalu sulit atau didokumentasikan dengan buruk jadi saya menyelesaikan ini dengan skrip sederhana swagger-yaml-to-html.py , yang berfungsi seperti ini

python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html

Ini untuk YAML tetapi memodifikasinya agar bekerja dengan JSON juga sepele.

oseiskar.dll
sumber
Juga tersedia sebagai buruh pelabuhan sekarang! github.com/yousan/swagger-yaml-to-html
noamtm
19

Lihat barang-barang cantik

Memiliki

  1. Mirip seperti panel kanan Swagger-Editor
  2. Cari / Filter
  3. Skema Lipat
  4. Umpan Balik Langsung
  5. Output sebagai file html tunggal

Saya melihat Swagger Editor dan mengira itu bisa mengekspor panel pratinjau tetapi ternyata tidak bisa. Jadi saya menulis versi saya sendiri.

Pengungkapan Penuh: Saya adalah pembuat alat tersebut.

TLJ
sumber
1
Saya telah menemukan pretty-swag sebagai alat yang langsung dan ideal, dengan CLI dan titik masuk API yang sesuai. Satu-satunya keluhan saya (dan yang memaksa saya untuk berurusan dengan kompleksitas swagger-ui) adalah kegagalannya menangani komposisi / ekstensi objek dengan benar. Setiap penggunaan allOfdalam dokumen menghasilkan undefined, bahkan dalam skenario yang paling sederhana ("menggabungkan" satu objek, setara dengan tidak menggunakan allOfsama sekali).
HonoredMule
3
Baru saja meluncurkan allOffitur untuk Anda. Coba lihat.
TLJ
2
Tampaknya tidak mendukung Swagger / OpenAPI V3
SeinopSys
16

Lihat proyek swagger-api / swagger-codegen di GitHub; proyek README menunjukkan bagaimana menggunakannya untuk menghasilkan HTML statis. Lihat Membuat dokumentasi api html statis .

Jika Anda ingin melihat swagger.json, Anda dapat menginstal UI Swagger dan menjalankannya. Anda cukup menerapkannya di server web (folder dist setelah Anda mengkloning repo dari GitHub) dan melihat UI Swagger di browser Anda. Ini adalah aplikasi JavaScript.

djb
sumber
Terima kasih. Masalah saya adalah swagger-ui tidak menerima spesifikasi 2.0. Namun, ini sepertinya jawaban yang paling sederhana, jadi saya akan menerimanya (untuk saat ini).
Salil
Alat Swagger masih berkembang untuk 2.0. Namun, saya telah menemukan Swagger UI berfungsi untuk file 2.0 saya yang dimulai dengan "swagger": "2.0",
djb
Selain itu, dari Swagger Editor, Anda dapat mengekspor spesifikasi JSON (bukan sebagai YAML tetapi sebagai JSON) dan Swagger UI harus dapat membacanya. (Catatan: swagger.json harus berada di host / port yang sama dengan aplikasi UI Swagger, atau Anda harus mengaktifkan CORS; lihat README.md di Editor Swagger di GitHub
djb
14

Saya menghabiskan banyak waktu dan mencoba banyak solusi berbeda - pada akhirnya saya melakukannya dengan cara ini:

<html>
    <head>    
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui.css">
        <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
        <script>

            function render() {
                var ui = SwaggerUIBundle({
                    url:  `path/to/my/swagger.yaml`,
                    dom_id: '#swagger-ui',
                    presets: [
                        SwaggerUIBundle.presets.apis,
                        SwaggerUIBundle.SwaggerUIStandalonePreset
                    ]
                });
            }

        </script>
    </head>

    <body onload="render()">
        <div id="swagger-ui"></div>
    </body>
</html>

Anda hanya perlu memiliki jalur / ke / my / swagger.yaml yang dilayani dari lokasi yang sama.
(atau gunakan header CORS)

Kris Randall
sumber
Keren terima kasih! Saya telah menggunakan <link rel = "stylesheet" href = " petstore.swagger.io/swagger-ui.css "> <script src = " petstore.swagger.io/swagger-ui-bundle.js "></script >
Erando
7

Anda juga dapat mengunduh ui swagger dari: https://github.com/swagger-api/swagger-ui , ambil folder dist, ubah index.html: ubah konstruktor

const ui = SwaggerUIBundle({
    url: ...,

ke

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

sekarang folder dist berisi semua yang Anda butuhkan dan dapat didistribusikan apa adanya

pengguna1928596
sumber
2

Lihat tautan ini: http://zircote.com/swagger-php/installation.html

  1. Unduh file phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
  2. Instal Komposer https://getcomposer.org/download/
  3. Buat composer.json
  4. Klon swagger-php / library
  5. Clone swagger-ui / library
  6. Membuat kelas Sumber Daya dan Model php untuk API
  7. Jalankan file PHP untuk menghasilkan json
  8. Berikan jalur json di api-doc.json
  9. Berikan jalur api-doc.json di index.php di dalam folder swagger-ui dist

Jika Anda membutuhkan bantuan lain, jangan ragu untuk bertanya.

Syed Raza Mehdi
sumber
1
Apakah ada editor online (selain swagger-editor) yang dapat membuatkan ini untuk saya? Saya tidak ingin membuat anotasi API PHP saya jika ada cara yang lebih sederhana. Masalahnya, saya telah menemukan bahwa swagger-editor menghasilkan spesifikasi swagger v2.0, dan swagger-ui tidak menanganinya sampai sekarang.
Salil
@Salil yang saya tahu adalah bahwa kesombongan menyediakan editor on-line sendiri yaitu editor.swagger.wordnik.com saya tidak mengetahui ada editor online lainnya, jika Anda menemukan ada yang membaginya dengan kami, terima kasih :)
Syed Raza Mehdi
2

Ada program Java kecil yang menghasilkan docs (adoc atau md) dari file yaml.

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.DE)
        .build();

Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);

Sayangnya itu hanya mendukung OpenAPI 2.0 tetapi tidak OpenAPI 3.0 .

Erando
sumber
2

Untuk Swagger API 3.0, menghasilkan kode klien Html2 dari Swagger Editor online sangat cocok untuk saya!

Kumar S
sumber