Unduh widdershins - pengunduhan kode sumber widdershins

widdershins

Kode sumber lainnya

v4.0.0

Unduh

lebih lebar

Definisi OpenAPI / Swagger / AsyncAPI / Semoasa ke penurunan harga yang kompatibel dengan Slate / ReSlate

Kata keterangan Widdershins :

Dalam arah yang berlawanan dengan arah matahari;
berlawanan arah jarum jam;
membantu Anda menghasilkan dokumentasi statis dari definisi OpenAPI 3.0 / Swagger 2.0 / AsyncAPI 1.x / Semoasa 0.1.0

Berita

Perubahan versi 4.0:
- Sekarang menggunakan Janji, bukan panggilan balik
- Pilihan untuk menampilkan html secara langsung, dan ke format ReSpec
- Contoh kode JavaScript dan Node.js terpadu, PHP menambahkan
- kolom restrictions ( readOnly / writeOnly ) ditambahkan ke templat skema
- Banyak perbaikan bug
Mulai v3.0.0 Widdershins tidak lagi memperluas definisi parameter isi OpenAPI/requestBodies secara default, kecuali jika memiliki skema inline. Anda dapat memulihkan perilaku lama dengan menggunakan opsi --expandBody .
Anda dapat membatasi kedalaman contoh skema menggunakan opsi --maxDepth . Standarnya adalah 10.
Untuk menghilangkan skema sepenuhnya, salin dan sesuaikan template main.dot .
Pada v3.1.0 Widdershins menyertakan header Authorization yang dihasilkan dalam sampel kode OpenAPI. Jika Anda ingin menghilangkan ini, lihat di sini.

Untuk menginstal

Kloning repositori git, dan npm i untuk menginstal dependensi, atau
npm install -g widdershins untuk menginstal secara global

Memulai

Widdershins umumnya digunakan sebagai tahapan dalam pipeline dokumentasi API. Pipeline dimulai dengan definisi API dalam format OpenAPI 3.x, OpenAPI 2.0 (fka Swagger), API Blueprint, AsyncAPI, atau Semoasa. Widdershins mengubah deskripsi ini menjadi penurunan harga yang cocok untuk digunakan oleh penyaji , seperti Slate, ReSlate, Shins ( tidak digunakan lagi ) atau html yang cocok untuk digunakan dengan ReSpec.

Jika Anda perlu membuat definisi API masukan, daftar editor yang tersedia ini mungkin berguna.

Dokumentasi lebih mendalam tersedia di sini.

Contoh

 node widdershins --search false --language_tabs 'ruby:Ruby' 'python:Python' --summary defs/petstore3.json -o petstore3.md

Pilihan

Nama parameter CLI	Nama parameter JavaScript	Jenis	Nilai bawaan	Keterangan
--papan klip	pilihan.papan klip	`boolean`	`true`	Menetapkan nilai properti `code_clipboard` di judul, sehingga pemroses penurunan harga dapat menyertakan dukungan clipboard.
--customApiKeyValue	pilihan.customApiKeyValue	`string`	`ApiKey`	Tetapkan nilai kunci API khusus untuk digunakan sebagai kunci API dalam contoh kode yang dihasilkan.
--expandBody	options.expandBody	`boolean`	`false`	Jika parameter requestBody suatu metode merujuk ke skema dengan referensi (bukan dengan skema inline), secara default, Widdershins hanya menampilkan referensi ke parameter ini. Setel opsi ini ke true untuk memperluas skema dan menampilkan semua properti di isi permintaan.
--judul	pilihan.judul	`integer`	2	Tetapkan nilai parameter `headingLevel` di header sehingga pemroses penurunan harga mengetahui berapa banyak level heading yang akan ditampilkan di daftar isi. Saat ini hanya didukung oleh Shins, bukan oleh Slate, yang tidak memiliki fitur ini.
--hilangkan Badan	options.omitBody	`boolean`	`false`	Secara default, Widdershins menyertakan parameter body sebagai baris dalam tabel parameter sebelum baris yang mewakili bidang di body. Setel parameter ini untuk menghilangkan baris parameter isi tersebut.
--hilangkanHeader	pilihan.omitHeader	`boolean`	`false`	Hilangkan materi depan header / YAML di file Markdown yang dihasilkan.
--menyelesaikan	pilihan.menyelesaikan	`boolean`	`false`	Selesaikan $refs eksternal, menggunakan parameter `source` atau file input sebagai lokasi dasar.
--skema dangkal	options.shallowSchemas	`boolean`	`false`	Saat merujuk ke skema dengan $ref, jangan tampilkan konten skema secara lengkap.
T/A	pilihan.sumber	`string`	Tidak ada	Lokasi absolut atau URL file sumber yang akan digunakan sebagai basis untuk menyelesaikan referensi relatif ($refs) dari; diperlukan jika options.resolve diatur ke true. Untuk perintah CLI, Widdershins menggunakan file input sebagai dasar untuk $refs.
--ringkasan	pilihan.tocSummary	`boolean`	`false`	Gunakan ringkasan operasi sebagai entri TOC, bukan ID.
--useBodyName	pilihan.useBodyName	`boolean`	Gunakan nama param asli untuk parameter isi OpenAPI 2.0.
-v, --bertele-tele	pilihan.verbose	`boolean`	`false`	Tingkatkan verbositas.
-h, --membantu	pilihan.bantuan	`boolean`	`false`	Tunjukkan bantuan.
--versi	pilihan.versi	`boolean`	`false`	Tampilkan nomor versi.
-c, --kode	options.codeSamples	`boolean`	`false`	Hilangkan contoh kode yang dihasilkan.
--httpsnippet	opsi.httpsnippet	`boolean`	`false`	Gunakan httpsnippet untuk menghasilkan contoh kode.
-d, --penemuan	pilihan.penemuan	`boolean`	`false`	Sertakan data penemuan WebAPI Schema.org.
-e, --lingkungan	T/A	`string`	Tidak ada	File untuk memuat opsi konfigurasi.
-i, --termasuk	pilihan.termasuk	`string`	Tidak ada	Daftar file yang akan dimasukkan ke dalam header `include` dari output Markdown. Prosesor seperti Shins kemudian dapat mengimpor konten file-file ini.
-l, --lang	pilihan.lang	`boolean`	`false`	Hasilkan daftar bahasa untuk contoh kode berdasarkan bahasa yang digunakan dalam contoh `x-code-samples` file sumber.
--bahasa_tab	pilihan.bahasa_tabs	`string`	(Berbeda untuk setiap jenis masukan)	Daftar tab bahasa untuk contoh kode menggunakan format bahasa[:label[:klien]], seperti `javascript:JavaScript:request` .
-m, --kedalaman maksimal	pilihan.maxDepth	`integer`	10	Kedalaman maksimum untuk ditampilkan pada contoh skema.
-o, --file keluar	T/A	`string`	Tidak ada	File untuk menulis penurunan harga keluaran. Jika dibiarkan kosong, Widdershins mengirimkan output ke stdout.
-r, --mentah	kebalikan dari options.sample	`boolean`	`false`	Keluarkan skema mentah, bukan nilai contoh.
-s, --cari	pilihan.pencarian	`boolean`	`true`	Tetapkan nilai parameter `search` di header sehingga pemroses penurunan harga seperti Slate menyertakan pencarian atau tidak dalam outputnya.
-t, --tema	pilihan.tema	`string`	darkula	Tema penyorot sintaks yang akan digunakan.
-u, --pengguna_template	pilihan.user_templates	`string`	Tidak ada	Direktori untuk memuat templat pengganti.
-x, --eksperimental	pilihan.eksperimental	`boolean`		Gunakan httpSnippet untuk tipe media multipart.
-y, --yaml	pilihan.yaml	`boolean`	`false`	Tampilkan skema JSON dalam format YAML.
	pilihan.templateCallback	`function`	Tidak ada	`function` yang dipanggil sebelum dan sesudah setiap templat (hanya kode JavaScript).
	options.toc_footers	`object`	Peta `url` dan `description` yang akan ditambahkan ke array footer ToC (hanya kode JavaScript).

Dalam kode Node.JS, buat objek opsi dan teruskan ke fungsi convert Widdershins, seperti dalam contoh ini:

 const converter = require ( 'widdershins' ) ;
let options = { } ; // defaults shown
options . codeSamples = true ;
options . httpsnippet = false ;
//options.language_tabs = [];
//options.language_clients = [];
//options.loadedFrom = sourceUrl; // only needed if input document is relative
//options.user_templates = './user_templates';
options . templateCallback = function ( templateName , stage , data ) { return data } ;
options . theme = 'darkula' ;
options . search = true ;
options . sample = true ; // set false by --raw
options . discovery = false ;
options . includes = [ ] ;
options . shallowSchemas = false ;
options . tocSummary = false ;
options . headings = 2 ;
options . yaml = false ;
//options.resolve = false;
//options.source = sourceUrl; // if resolve is true, must be set to full path or URL of the input document
converter . convert ( apiObj , options )
. then ( str => {
  // str contains the converted markdown
} )
. catch ( err => {
  console . error ( err ) ;
} ) ;

Untuk hanya menyertakan subkumpulan tab bahasa yang telah ditentukan sebelumnya, atau untuk mengganti nama nama tampilannya, Anda dapat mengganti options.language_tabs :

 options . language_tabs = [ { 'go' : 'Go' } , { 'http' : 'HTTP' } , { 'javascript' : 'JavaScript' } , { 'javascript--node' : 'Node.JS' } , { 'python' : 'Python' } , { 'ruby' : 'Ruby' } ] ;

Opsi --environment menentukan objek options berformat JSON atau YAML, misalnya:

{
  "language_tabs" : [{ "go" : " Go " }, { "http" : " HTTP " }, { "javascript" : " JavaScript " }, { "javascript--node" : " Node.JS " }, { "python" : " Python " }, { "ruby" : " Ruby " }],
  "verbose" : true ,
  "tagGroups" : [
    {
      "title" : " Companies " ,
      "tags" : [ " companies " ]
    },
    {
      "title" : " Billing " ,
      "tags" : [ " invoice-create " , " invoice-close " , " invoice-delete " ]
    }
  ]
}

Anda juga dapat menggunakan file lingkungan untuk mengelompokkan jalur yang diberi tag OAS/Swagger untuk membuat daftar isi yang lebih elegan, dan struktur halaman keseluruhan.

Jika Anda perlu mendukung versi Slate <v1.5.0 (atau penyaji yang juga tidak mendukung nama tampilan untuk tab bahasa, seperti node-slate , slate-node atau whiteboard ), Anda dapat menggunakan --environment opsi --environment dengan file whiteboard_env.json yang disertakan untuk mencapai hal ini.

Jika Anda menggunakan opsi httpsnippet untuk menghasilkan contoh kode, Anda dapat menentukan pustaka klien yang digunakan untuk melakukan permintaan untuk setiap bahasa dengan mengganti options.language_clients :

 options . language_clients = [ { 'shell' : 'curl' } , { 'node' : 'request' } , { 'java' : 'unirest' } ] ;

Jika nama bahasa berbeda antara nama penurunan harga yang diperlukan untuk penyorotan sintaksis dan target httpsnippet yang diperlukan, keduanya dapat ditentukan dalam formulir markdown--target .

Untuk melihat daftar bahasa dan klien yang didukung oleh httpsnippet, klik di sini.

Opsi loadedFrom hanya diperlukan jika definisi OpenAPI/Swagger tidak menentukan host, dan (sesuai spesifikasi OpenAPI) titik akhir API dianggap berdasarkan pada URL sumber asal definisi tersebut dimuat.

Untuk melihat daftar tema penyorotan sintaks highlight-js, klik di sini.

Data penemuan WebAPI Schema.org disertakan jika opsi discovery di atas disetel true . Lihat Grup Komunitas Penemuan WebAPI W3C untuk informasi lebih lanjut.

Tab bahasa

Widdershins mendukung ekstensi vendor x-code-samples untuk sepenuhnya menyesuaikan dokumentasi Anda. Alternatifnya, Anda dapat mengedit contoh kode default di subdirektori templates , atau menggantinya menggunakan opsi user_templates untuk menentukan direktori yang berisi templat Anda.

Widdershins mendukung penggunaan beberapa tab bahasa dengan bahasa yang sama (yaitu Javascript biasa dan Node.Js). Untuk menggunakan dukungan ini, Anda harus menggunakan Slate (atau salah satu portnya yang kompatibel) versi 1.5.0 atau lebih tinggi.

Templat

Secara default, Widdershins menggunakan template di folder templates/ untuk menghasilkan output Markdown. Untuk menyesuaikan templat, salin beberapa atau semuanya ke folder dan teruskan lokasinya ke parameter user_templates .

Templatnya mencakup templat .dot dan .def parsial. Untuk mengganti templat .dot , Anda harus menyalinnya dan bagian .def turunan yang direferensikan oleh templat tersebut. Demikian pula, untuk mengganti sebagian .def , Anda juga harus menyalin templat .dot induk. Untuk OpenAPI 3, templat utamanya adalah main.dot dan bagian turunan utamanya adalah parameters.def , responses.def , dan callbacks.def .

Ini berarti biasanya paling mudah untuk menyalin semua file .dot dan .def ke direktori template pengguna Anda sehingga Anda tidak melewatkan satu template atau sebagian. Untuk menerapkan perubahan dari pembaruan Widdershins, Anda dapat menggunakan alat diff visual yang dapat berjalan di dua direktori, seperti Meld atau WinMerge.

Sintaks templat

Templat dikompilasi dengan doT.js.

Templat memiliki akses ke objek data dengan serangkaian properti berdasarkan konteks dokumen. Untuk informasi tentang parameter, lihat file README untuk templat yang sesuai:

Parameter templat Swagger 2.0 / OpenAPI 3.0.x
Parameter templat AsyncAPI 1.x
Parameter templat Semoasa 0.1.0

Untuk mencetak nilai parameter atau variabel dalam template, gunakan kode {{=parameterName}} . Misalnya, untuk mencetak judul spesifikasi OpenAPI 3 (dari kolom info.title ), gunakan kode {{=data.api.info.title}} .

Untuk melakukan perulangan nilai dalam array, gunakan kode {{~ arrayName :tempVariable}} untuk memulai perulangan dan kode {{~}} untuk menutup perulangan. Misalnya, parameters.def parsial OpenAPI 3.def menggunakan kode ini untuk membuat tabel parameter dalam suatu operasi:

 |Name|In|Type|Required|Description|
|---|---|---|---|---|
{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{=p.safeType}}|{{=p.required}}|{{=p.shortDesc || 'none'}}|
{{~}}

Untuk logika if/then, gunakan kode {{? booleanExpression}} untuk memulai blok kode dan kode {{?}} untuk menutup blok. Misalnya, templat main.dot OpenAPI 3 memanggil sebagian security.def untuk menampilkan informasi tentang skema keamanan jika spesifikasi OpenAPI menyertakan bagian securitySchemes :

 {{? data.api.components && data.api.components.securitySchemes }}
{{#def.security}}
{{?}}

Anda dapat menjalankan JavaScript sembarang di dalam templat dengan menyisipkan blok kode di dalam kurung kurawal. Misalnya, kode ini membuat variabel dan mereferensikannya dengan sintaksis doT.js normal nanti di templat:

 {{ {
let message = "Hello!";
} }}

{{=message}}

Panggilan balik templat

Parameter templateCallback menunjuk ke fungsi yang dipanggil Widdershins sebelum dan sesudah setiap template dijalankan. Fungsi callback menerima objek data yang berisi spesifikasi yang sedang diproses Widdershins; fungsi harus mengembalikan objek ini. Anda dapat menggunakan fungsi panggilan balik hanya jika Anda memanggil Widdershins dari kode JavaScript, bukan dari baris perintah.

Widdershins meneruskan variabel-variabel ini ke fungsi panggilan balik:

templateName : Nama template, misalnya main .
stage : Apakah Widdershins memanggil fungsi panggilan balik sebelum ( pre ) atau setelah ( post ) templat.
data : Objek yang berisi data yang sedang diproses Widdershins. Anda dapat mengubah objek data dengan cara apa pun yang Anda inginkan, namun fungsi harus mengembalikannya baik itu mengubahnya atau tidak. Konten yang Anda masukkan ke dalam properti data.append ditambahkan ke aliran keluaran saat ini.

Misalnya, kode JavaScript ini mencetak nama templat dan tahap pemrosesan pada output Markdown:

 'use strict' ;

const converter = require ( 'widdershins' ) ;
const fs = require ( 'fs' ) ;

let options = { } ;
options . templateCallback = myCallBackFunction ;

function myCallBackFunction ( templateName , stage , data ) {
  let statusString = "Template name: " + templateName + "n" ;
  statusString += "Stage: " + stage + "n" ;
  data . append = statusString ;
  return data ;
}

const apiObj = JSON . parse ( fs . readFileSync ( 'defs/petstore3.json' ) ) ;

converter . convert ( apiObj , options )
. then ( str => {
  fs . writeFileSync ( 'petstore3Output.md' , str , 'utf8' ) ;
} ) ;