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. يبدأ المسار بتعريف واجهة برمجة التطبيقات بتنسيق 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	اسم معلمة جافا سكريبت	يكتب	القيمة الافتراضية	وصف
--الحافظة	options.clipboard	`boolean`	`true`	يضبط قيمة الخاصية `code_clipboard` في العنوان، بحيث يمكن لمعالجات تخفيض السعر تضمين دعم الحافظة.
--customApiKeyValue	options.customApiKeyValue	`string`	`ApiKey`	قم بتعيين قيمة مفتاح API مخصصة لاستخدامها كمفتاح API في أمثلة التعليمات البرمجية التي تم إنشاؤها.
--expandBody	options.expandBody	`boolean`	`false`	إذا كانت معلمة requestBody الخاصة بالأسلوب تشير إلى مخطط حسب المرجع (وليس مع مخطط مضمن)، بشكل افتراضي، يعرض Widdershins مرجعًا فقط لهذه المعلمة. اضبط هذا الخيار على true لتوسيع المخطط وإظهار كافة الخصائص في نص الطلب.
--العناوين	options.headings	`integer`	2	قم بتعيين قيمة معلمة `headingLevel` في الرأس حتى تعرف معالجات تخفيض السعر عدد مستويات العناوين التي سيتم عرضها في جدول المحتويات. مدعوم حاليًا فقط بواسطة Shins، وليس بواسطة Slate، الذي يفتقر إلى هذه الميزة.
--omitBody	options.omitBody	`boolean`	`false`	افتراضيًا، يقوم Widdershins بتضمين معلمة النص كصف في جدول المعلمات قبل الصفوف التي تمثل الحقول الموجودة في النص. قم بتعيين هذه المعلمة لحذف صف معلمة النص هذا.
--omitHeader	options.omitHeader	`boolean`	`false`	احذف العنوان الأمامي / YAML في ملف Markdown الذي تم إنشاؤه.
--حل	options.resolve	`boolean`	`false`	قم بحل مراجع $ الخارجية، باستخدام المعلمة `source` أو ملف الإدخال كموقع أساسي.
--shallowSchemas	options.shallowSchemas	`boolean`	`false`	عند الإشارة إلى مخطط يحتوي على $ref، لا تعرض محتويات المخطط بالكامل.
لا يوجد	options.source	`string`	لا أحد	الموقع المطلق أو عنوان URL للملف المصدر الذي سيتم استخدامه كقاعدة لتحليل المراجع النسبية ($refs) من؛ مطلوب إذا تم تعيين options.resolve على true. بالنسبة لأوامر واجهة سطر الأوامر (CLI)، يستخدم Widdershins ملف الإدخال كأساس للمراجع $.
--ملخص	options.tocSummary	`boolean`	`false`	استخدم ملخص العملية كإدخال جدول المحتويات بدلاً من المعرف.
--useBodyName	options.useBodyName	`boolean`	استخدم اسم المعلمة الأصلي لمعلمة نص OpenAPI 2.0.
-v، --verbose	options.verbose	`boolean`	`false`	زيادة اللفظ.
-ح، --مساعدة	خيارات. مساعدة	`boolean`	`false`	إظهار المساعدة.
--إصدار	options.version	`boolean`	`false`	إظهار رقم الإصدار.
-ج، --كود	options.codeSamples	`boolean`	`false`	حذف نماذج التعليمات البرمجية التي تم إنشاؤها.
--httpsnippet	options.httpsnippet	`boolean`	`false`	استخدم httpsnippet لإنشاء نماذج التعليمات البرمجية.
-د، -الاكتشاف	options.discovery	`boolean`	`false`	قم بتضمين بيانات اكتشاف schema.org WebAPI.
-ه، - البيئة	لا يوجد	`string`	لا أحد	ملف لتحميل خيارات التكوين من.
-i، - يشمل	options.includes	`string`	لا أحد	قائمة الملفات التي سيتم وضعها في رأس `include` لـ Markdown للإخراج. يمكن للمعالجات مثل Shins بعد ذلك استيراد محتويات هذه الملفات.
-ل، --لانج	options.lang	`boolean`	`false`	قم بإنشاء قائمة اللغات لنماذج التعليمات البرمجية بناءً على اللغات المستخدمة في أمثلة `x-code-samples` للملف المصدر.
--language_tabs	options.language_tabs	`string`	(يختلف لكل نوع إدخال)	قائمة علامات تبويب اللغة لنماذج التعليمات البرمجية باستخدام تنسيق language[:label[:client]]، مثل `javascript:JavaScript:request` .
-م، --ماكس ديبث	options.maxDepth	`integer`	10	أقصى عمق لإظهاره لأمثلة المخطط.
-o، --outfile	لا يوجد	`string`	لا أحد	ملف لكتابة تخفيض الانتاج ل. إذا تركت فارغة، يرسل Widdershins الإخراج إلى stdout.
-ص، --خام	معكوس options.sample	`boolean`	`false`	إخراج المخططات الأولية بدلاً من قيم الأمثلة.
-s، --بحث	خيارات.بحث	`boolean`	`true`	قم بتعيين قيمة معلمة `search` في الرأس بحيث تقوم معالجات Markdown مثل Slate بتضمين البحث أم لا في مخرجاتها.
-t، --الموضوع	options.theme	`string`	darkula	موضوع تمييز بناء الجملة للاستخدام.
-u، --user_templates	options.user_templates	`string`	لا أحد	الدليل لتحميل قوالب التجاوز منه.
-x، --تجريبية	options.experimental	`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 :

 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) تعتبر نقطة نهاية واجهة برمجة التطبيقات مبنية على عنوان URL المصدر الذي تم تحميل التعريف منه.

لرؤية قائمة السمات المميزة لبناء جملة Highlight-js، انقر هنا.

يتم تضمين بيانات اكتشاف Schema.org WebAPI إذا تم تعيين خيار discovery أعلاه على true . راجع مجموعة W3C WebAPI Discovery Community لمزيد من المعلومات.

علامات تبويب اللغة

يدعم 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، يمكنك استخدام أداة diff المرئية التي يمكن تشغيلها عبر دليلين، مثل Meld أو WinMerge.

بناء جملة القالب

يتم تجميع القوالب باستخدام doT.js.

تتمتع القوالب بإمكانية الوصول إلى كائن data بمجموعة من الخصائص بناءً على سياق المستند. للحصول على معلومات حول المعلمات، راجع ملف README للحصول على القوالب المناسبة:

معلمات قالب Swagger 2.0 / OpenAPI 3.0.x
معلمات قالب AsyncAPI 1.x
معلمات قالب Semosa 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' ) ;
} ) ;