widdershins ดาวน์โหลด - widdershins ดาวน์โหลดซอร์สโค้ด

widdershins

ซอร์สโค้ดอื่น ๆ

v4.0.0

ดาวน์โหลด

หน้ากว้าง

คำจำกัดความของ OpenAPI / Swagger / AsyncAPI / Semoasa เป็นมาร์กดาวน์ที่เข้ากันได้กับ Slate / ReSlate

คำวิเศษณ์ Widdershins :

ในทิศทางที่ขัดกับวิถีของดวงอาทิตย์
ทวนเข็มนาฬิกา;
ช่วยคุณสร้างเอกสารคงที่จากคำจำกัดความ OpenAPI 3.0 / Swagger 2.0 / AsyncAPI 1.x / Semoasa 0.1.0

ข่าว

การเปลี่ยนแปลงเวอร์ชัน 4.0:
- ตอนนี้ใช้สัญญาไม่ใช่การโทรกลับ
- ตัวเลือกในการส่งออก html โดยตรงและเป็นรูปแบบ ReSpec
- ตัวอย่างโค้ด JavaScript และ Node.js แบบรวม เพิ่ม PHP แล้ว
- เพิ่มคอลัมน์ restrictions ( readOnly / writeOnly ) ลงในเทมเพลตสคีมา
- แก้ไขข้อผิดพลาดมากมาย
ตั้งแต่เวอร์ชัน 3.0.0 Widdershins จะไม่ขยายคำจำกัดความของพารามิเตอร์เนื้อหา OpenAPI / requestBodies ตามค่าเริ่มต้นอีกต่อไป เว้นแต่จะมีสคีมาแบบอินไลน์ คุณสามารถคืนค่าลักษณะการทำงานเก่าได้โดยใช้ตัวเลือก --expandBody
คุณสามารถจำกัดความลึกของตัวอย่างสคีมาได้โดยใช้ตัวเลือก --maxDepth ค่าเริ่มต้นคือ 10
หากต้องการละเว้นสคีมาทั้งหมด โปรดคัดลอกและปรับแต่งเทมเพลต main.dot
ตั้งแต่เวอร์ชัน 3.1.0 Widdershins มีส่วนหัว Authorization ที่สร้างขึ้นในตัวอย่างโค้ด OpenAPI หากคุณต้องการละเว้นสิ่งนี้ ดูที่นี่

ในการติดตั้ง

โคลนที่เก็บ git และ npm i เพื่อติดตั้งการขึ้นต่อกันหรือ
npm install -g widdershins เพื่อติดตั้งแบบโกลบอล

เริ่มต้นใช้งาน

โดยทั่วไป Widdershins จะใช้เป็นระยะในไปป์ไลน์เอกสาร API ไปป์ไลน์เริ่มต้นด้วยคำจำกัดความ API ใน OpenAPI 3.x, OpenAPI 2.0 (fka Swagger), API Blueprint, AsyncAPI หรือรูปแบบ Semoasa Widdershins แปลงคำอธิบายนี้เป็นมาร์กดาวน์ที่เหมาะสำหรับการใช้งานโดย ตัวเรนเดอร์ เช่น Slate, ReSlate, Shins ( เลิกใช้แล้ว ) หรือ html ที่เหมาะสำหรับใช้กับ ReSpec

หากคุณต้องการสร้างคำจำกัดความ API อินพุต รายการตัวแก้ไขที่มีอยู่นี้อาจมีประโยชน์

มีเอกสารเชิงลึกเพิ่มเติมอยู่ที่นี่

ตัวอย่าง

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

ตัวเลือก

ชื่อพารามิเตอร์ CLI	ชื่อพารามิเตอร์ JavaScript	พิมพ์	ค่าเริ่มต้น	คำอธิบาย
--คลิปบอร์ด	options.คลิปบอร์ด	`boolean`	`true`	ตั้งค่าของคุณสมบัติ `code_clipboard` ในส่วนหัว เพื่อให้ตัวประมวลผล markdown สามารถรวมการสนับสนุนคลิปบอร์ดได้
--customApiKeyValue	options.customApiKeyValue	`string`	`ApiKey`	ตั้งค่าคีย์ API ที่กำหนดเองเพื่อใช้เป็นคีย์ API ในตัวอย่างโค้ดที่สร้างขึ้น
--expandBody	options.expandBody	`boolean`	`false`	หากพารามิเตอร์ requestBody ของเมธอดอ้างอิงถึงสคีมาโดยการอ้างอิง (ไม่ใช่กับสคีมาอินไลน์) ตามค่าเริ่มต้น Widdershins จะแสดงเฉพาะการอ้างอิงถึงพารามิเตอร์นี้ ตั้งค่าตัวเลือกนี้เป็นจริงเพื่อขยายสคีมาและแสดงคุณสมบัติทั้งหมดในเนื้อหาคำขอ
--หัวเรื่อง	ตัวเลือก.หัวเรื่อง	`integer`	2	ตั้งค่าของพารามิเตอร์ `headingLevel` ในส่วนหัว เพื่อให้ตัวประมวลผล markdown รู้จำนวนระดับส่วนหัวที่จะแสดงในสารบัญ ปัจจุบันรองรับโดย Shins เท่านั้น ไม่ใช่โดย Slate ซึ่งไม่มีฟีเจอร์นี้
--ละเว้นBody	options.ละเว้นBody	`boolean`	`false`	ตามค่าเริ่มต้น Widdershins จะรวมพารามิเตอร์เนื้อหาเป็นแถวในตารางพารามิเตอร์ก่อนแถวที่แสดงถึงฟิลด์ในเนื้อหา ตั้งค่าพารามิเตอร์นี้เพื่อละเว้นแถวพารามิเตอร์เนื้อหานั้น
--ละเว้นHeader	options.omitHeader	`boolean`	`false`	ละเว้นส่วนหัว / YAML front-matter ในไฟล์ Markdown ที่สร้างขึ้น
--แก้ไข	ตัวเลือกแก้ไข	`boolean`	`false`	แก้ไข $refs ภายนอก โดยใช้พารามิเตอร์ `source` หรือไฟล์อินพุตเป็นตำแหน่งฐาน
--shallowSchemas	options.shallowSchemas	`boolean`	`false`	เมื่ออ้างถึงสคีมาด้วย $ref อย่าแสดงเนื้อหาทั้งหมดของสคีมา
ไม่มี	ตัวเลือก.แหล่งที่มา	`string`	ไม่มี	ตำแหน่งที่แน่นอนหรือ URL ของไฟล์ต้นฉบับที่จะใช้เป็นฐานในการแก้ไขการอ้างอิงแบบสัมพันธ์ ($refs) จำเป็นหากตั้งค่า options.resolve เป็นจริง สำหรับคำสั่ง CLI นั้น Widdershins จะใช้ไฟล์อินพุตเป็นฐานสำหรับ $refs
--สรุป	options.tocสรุป	`boolean`	`false`	ใช้สรุปการดำเนินการเป็นรายการ TOC แทน ID
--useBodyName	options.useBodyName	`boolean`	ใช้ชื่อพารามิเตอร์ดั้งเดิมสำหรับพารามิเตอร์เนื้อหาของ OpenAPI 2.0
-v, --verbose	ตัวเลือก verbose	`boolean`	`false`	เพิ่มความฟุ่มเฟือย
-h, --ช่วยด้วย	ตัวเลือกความช่วยเหลือ	`boolean`	`false`	แสดงความช่วยเหลือ
--รุ่น	ตัวเลือก.รุ่น	`boolean`	`false`	แสดงหมายเลขเวอร์ชัน
-c, --รหัส	options.codeSamples	`boolean`	`false`	ละเว้นตัวอย่างโค้ดที่สร้างขึ้น
--httpsnippet	options.httpsnippet	`boolean`	`false`	ใช้ httpsnippet เพื่อสร้างตัวอย่างโค้ด
-d, --การค้นพบ	ตัวเลือกการค้นพบ	`boolean`	`false`	รวมข้อมูลการค้นพบ WebAPI ของ schema.org
-e, --สิ่งแวดล้อม	ไม่มี	`string`	ไม่มี	ไฟล์ที่จะโหลดตัวเลือกการกำหนดค่า
-i, --รวมถึง	ตัวเลือก.รวม	`string`	ไม่มี	รายการไฟล์ที่จะใส่ในส่วนหัว `include` ของเอาต์พุต Markdown โปรเซสเซอร์เช่น Shins จะสามารถนำเข้าเนื้อหาของไฟล์เหล่านี้ได้
-ล, --lang	options.lang	`boolean`	`false`	สร้างรายการภาษาสำหรับตัวอย่างโค้ดตามภาษาที่ใช้ในตัวอย่าง `x-code-samples` ของไฟล์ต้นฉบับ
--ภาษา_แท็บ	options.ภาษา_แท็บ	`string`	(แตกต่างกันไปตามอินพุตแต่ละประเภท)	รายการแท็บภาษาสำหรับตัวอย่างโค้ดที่ใช้รูปแบบ language[:label[:client]] เช่น `javascript:JavaScript:request`
-m, --maxDepth	ตัวเลือก. maxDepth	`integer`	10	ความลึกสูงสุดที่จะแสดงสำหรับตัวอย่างสคีมา
-o, --outfile	ไม่มี	`string`	ไม่มี	ไฟล์ที่จะเขียนมาร์กดาวน์เอาต์พุต หากเว้นว่างไว้ Widdershins จะส่งเอาต์พุตไปที่ stdout
-r, --ดิบ	ผกผัน ของตัวเลือกตัวอย่าง	`boolean`	`false`	ส่งออกสคีมาดิบแทนค่าตัวอย่าง
-s, --ค้นหา	ตัวเลือกการค้นหา	`boolean`	`true`	ตั้งค่าของพารามิเตอร์ `search` ในส่วนหัวเพื่อให้ตัวประมวลผล Markdown เช่น Slate รวมการค้นหาไว้ในเอาต์พุตหรือไม่
-t, --ธีม	ตัวเลือก.ธีม	`string`	ดาร์คูลา	ธีมเน้นไวยากรณ์ที่จะใช้
-u, --user_templates	options.user_templates	`string`	ไม่มี	ไดเร็กทอรีสำหรับโหลดเทมเพลตแทนที่
-x, --ทดลอง	ตัวเลือกการทดลอง	`boolean`		ใช้ httpSnippet สำหรับสื่อประเภทหลายส่วน
-y, --yaml	options.yaml	`boolean`	`false`	แสดงสคีมา JSON ในรูปแบบ YAML
	options.templateCallback	`function`	ไม่มี	`function` ที่ถูกเรียกก่อนและหลังแต่ละเทมเพลต (โค้ด JavaScript เท่านั้น)
	options.toc_footers	`object`	แผนที่ของ `url` และ `description` ที่จะเพิ่มลงในอาร์เรย์ส่วนท้าย ToC (โค้ด JavaScript เท่านั้น)

ในโค้ด Node.JS ให้สร้างออบเจ็กต์ตัวเลือกและส่งไปยังฟังก์ชัน convert Widdershins ดังในตัวอย่างนี้:

 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 ) ;
} ) ;

หากต้องการรวมเฉพาะชุดย่อยของแท็บภาษาที่กำหนดไว้ล่วงหน้า หรือหากต้องการเปลี่ยนชื่อที่แสดง คุณสามารถแทนที่ options.language_tabs . language_tabs :

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

ตัวเลือก --environment ระบุออบเจ็กต์ options ที่จัดรูปแบบ JSON หรือ YAML เช่น:

{
  "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 " ]
    }
  ]
}

คุณยังสามารถใช้ไฟล์สภาพแวดล้อมเพื่อจัดกลุ่มเส้นทางที่แท็ก OAS/Swagger ไว้ด้วยกันเพื่อสร้างสารบัญที่สวยงามยิ่งขึ้น และโครงสร้างหน้าโดยรวม

หากคุณต้องการรองรับเวอร์ชันของ Slate <v1.5.0 (หรือตัวเรนเดอร์ที่ไม่รองรับชื่อที่แสดงสำหรับแท็บภาษา เช่น node-slate , slate-node หรือ whiteboard ) คุณสามารถใช้ --environment ตัวเลือก --environment พร้อมไฟล์ whiteboard_env.json ที่รวมอยู่เพื่อให้บรรลุเป้าหมายนี้

หากคุณใช้ตัวเลือก httpsnippet เพื่อสร้างตัวอย่างโค้ด คุณสามารถระบุไลบรารีไคลเอ็นต์ที่ใช้ในการดำเนินการคำขอสำหรับแต่ละภาษาได้โดยการแทนที่ options.language_clients :

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

หากชื่อภาษาแตกต่างกันระหว่างชื่อมาร์กดาวน์ที่จำเป็นสำหรับการเน้นไวยากรณ์และเป้าหมาย httpsnippet ที่จำเป็น ทั้งสองสามารถระบุได้ในแบบฟอร์ม markdown--target

หากต้องการดูรายการภาษาและไคลเอนต์ที่ httpsnippet รองรับ คลิกที่นี่

ตัวเลือก loadedFrom จำเป็นเฉพาะในกรณีที่คำจำกัดความของ OpenAPI / Swagger ไม่ได้ระบุโฮสต์ และ (ตามข้อกำหนดของ OpenAPI) จุดสิ้นสุด API จะถือว่าเป็นไปตาม URL แหล่งที่มาที่มีการโหลดคำจำกัดความ

หากต้องการดูรายการธีมที่เน้นไวยากรณ์ highlight-js คลิกที่นี่

ข้อมูลการค้นพบ Schema.org WebAPI จะรวมอยู่ด้วยหากตัวเลือก discovery ด้านบนตั้งค่าเป็น true ดูกลุ่มชุมชนการค้นพบ W3C WebAPI สำหรับข้อมูลเพิ่มเติม

แท็บภาษา

Widdershins รองรับส่วนขยายผู้ขาย x-code-samples เพื่อปรับแต่งเอกสารของคุณอย่างสมบูรณ์ หรือคุณสามารถแก้ไขตัวอย่างโค้ดเริ่มต้นในไดเร็กทอรีย่อย templates หรือแทนที่โดยใช้ตัวเลือก user_templates เพื่อระบุไดเร็กทอรีที่มีเทมเพลตของคุณ

Widdershins รองรับการใช้แท็บหลายภาษาที่มีภาษาเดียวกัน (เช่น Javascript ธรรมดาและ Node.Js) หากต้องการใช้การสนับสนุนนี้ คุณต้องใช้ Slate (หรือพอร์ตใดพอร์ตหนึ่งที่เข้ากันได้กับ) เวอร์ชัน 1.5.0 หรือสูงกว่า

เทมเพลต

ตามค่าเริ่มต้น Widdershins จะใช้เทมเพลตใน templates/ โฟลเดอร์เพื่อสร้างเอาต์พุต Markdown หากต้องการปรับแต่งเทมเพลต ให้คัดลอกบางส่วนหรือทั้งหมดไปยังโฟลเดอร์และส่งตำแหน่งไปยังพารามิเตอร์ user_templates

เทมเพลตประกอบด้วยเทมเพลต .dot และ .def บางส่วน หากต้องการแทนที่เทมเพลต .dot คุณต้องคัดลอกเทมเพลตนั้นและรายการย่อย .def บางส่วนที่เทมเพลตอ้างอิงถึง ในทำนองเดียวกัน หากต้องการแทนที่ .def บางส่วน คุณต้องคัดลอกเทมเพลต .dot ระดับบนสุดด้วย สำหรับ OpenAPI 3 เทมเพลตหลักคือ main.dot และส่วนย่อยหลักคือ parameters.def , responses.def และ callbacks.def

ซึ่งหมายความว่าโดยปกติแล้วจะง่ายที่สุดในการคัดลอกไฟล์ .dot และ .def ทั้งหมดไปยังไดเร็กทอรีเทมเพลตผู้ใช้ของคุณ ดังนั้นคุณจึงไม่ข้ามเทมเพลตหรือบางส่วน หากต้องการนำการเปลี่ยนแปลงมาจากการอัปเดต Widdershins คุณสามารถใช้เครื่องมือ Visual diff ซึ่งสามารถทำงานในสองไดเร็กทอรี เช่น Meld หรือ WinMerge

ไวยากรณ์เทมเพลต

เทมเพลตถูกคอมไพล์ด้วย doT.js

เทมเพลตสามารถเข้าถึงออบเจ็กต์ data ที่มีคุณสมบัติหลากหลายตามบริบทของเอกสาร สำหรับข้อมูลเกี่ยวกับพารามิเตอร์ โปรดดูไฟล์ README สำหรับเทมเพลตที่เหมาะสม:

พารามิเตอร์เทมเพลต Swagger 2.0 / OpenAPI 3.0.x
พารามิเตอร์เทมเพลต AsyncAPI 1.x
พารามิเตอร์เทมเพลต Semoasa 0.1.0

หากต้องการพิมพ์ค่าของพารามิเตอร์หรือตัวแปรในเทมเพลต ให้ใช้โค้ด {{=parameterName}} ตัวอย่างเช่น หากต้องการพิมพ์ชื่อของข้อกำหนด OpenAPI 3 (จากช่อง info.title ) ให้ใช้โค้ด {{=data.api.info.title}}

หากต้องการวนซ้ำค่าในอาร์เรย์ ให้ใช้โค้ด {{~ arrayName :tempVariable}} เพื่อเริ่มการวนซ้ำ และใช้โค้ด {{~}} เพื่อปิดการวนซ้ำ ตัวอย่างเช่น parameters.def บางส่วนของ OpenAPI 3.def ใช้โค้ดนี้เพื่อสร้างตารางของพารามิเตอร์ในการดำเนินการ:

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

สำหรับตรรกะ if/then ให้ใช้โค้ด {{? booleanExpression}} เพื่อเริ่มบล็อกโค้ดและโค้ด {{?}} เพื่อปิดบล็อก ตัวอย่างเช่น เทมเพลต OpenAPI 3 main.dot เรียก security.def บางส่วนเพื่อแสดงข้อมูลเกี่ยวกับรูปแบบการรักษาความปลอดภัย หากข้อกำหนดของ OpenAPI มีส่วน securitySchemes ด้วย:

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

คุณสามารถเรียกใช้ JavaScript ภายในเทมเพลตได้ตามใจชอบโดยการแทรกบล็อคโค้ดภายในเครื่องหมายปีกกา ตัวอย่างเช่น โค้ดนี้จะสร้างตัวแปรและอ้างอิงตัวแปรด้วยไวยากรณ์ doT.js ปกติในเทมเพลตในภายหลัง:

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

{{=message}}

การโทรกลับเทมเพลต

พารามิเตอร์ templateCallback ชี้ไปที่ฟังก์ชันที่ Widdershins เรียกใช้ก่อนและหลังแต่ละเทมเพลตทำงาน ฟังก์ชันการโทรกลับได้รับออบเจ็กต์ data ที่มีข้อมูลจำเพาะที่ Widdershins กำลังประมวลผล ฟังก์ชันจะต้องส่งคืนวัตถุนี้ คุณสามารถใช้ฟังก์ชันโทรกลับได้ก็ต่อเมื่อคุณเรียก Widdershins จากโค้ด JavaScript ไม่ใช่จากบรรทัดคำสั่ง

Widdershins ส่งผ่านตัวแปรเหล่านี้ไปยังฟังก์ชันโทรกลับ:

templateName : ชื่อของเทมเพลต เช่น main .
stage : ไม่ว่า Widdershins จะเรียกใช้ฟังก์ชันการโทรกลับก่อน ( pre ) หรือหลัง ( post ) เทมเพลต
data : ออบเจ็กต์ที่มีข้อมูลที่ Widdershins กำลังประมวลผล คุณสามารถกลายพันธุ์วัตถุ data ด้วยวิธีใดก็ได้ที่คุณเห็นว่าเหมาะสม แต่ฟังก์ชันจะต้องส่งคืนไม่ว่าจะเปลี่ยนแปลงหรือไม่ก็ตาม เนื้อหาที่คุณใส่ในคุณสมบัติ data.append จะถูกผนวกเข้ากับกระแสข้อมูลขาออกปัจจุบัน

ตัวอย่างเช่น โค้ด JavaScript นี้จะพิมพ์ชื่อของเทมเพลตและขั้นตอนการประมวลผลในเอาต์พุต 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' ) ;
} ) ;