widdershins
v4.0.0
Определение OpenAPI/Swagger/AsyncAPI/Semoasa для уценки, совместимой с Slate/ReSlate
restrictions ( readOnly / writeOnly ) добавлен в шаблоны схем--expandBody .--maxDepth . По умолчанию — 10.main.dot .Authorization в примеры кода OpenAPI. Если вы хотите опустить это, см. здесь.npm i , чтобы установить зависимости, илиnpm install -g widdershins для глобальной установкиВиддершинс обычно используется в качестве этапа в конвейере документации API. Конвейер начинается с определения API в формате OpenAPI 3.x, OpenAPI 2.0 (fka Swagger), API Blueprint, AsyncAPI или Semoasa. Виддершинс преобразует это описание в уценку, подходящую для использования средством рендеринга , например 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 | Тип | Значение по умолчанию | Описание |
|---|---|---|---|---|
| --буфер обмена | параметры.буфер обмена | boolean | true | Устанавливает значение свойства code_clipboard в заголовке, чтобы процессоры уценки могли включать поддержку буфера обмена. |
| --customApiKeyValue | options.customApiKeyValue | string | ApiKey | Установите значение пользовательского ключа API, который будет использоваться в качестве ключа API в сгенерированных примерах кода. |
| --expandBody | options.expandBody | boolean | false | Если параметр requestBody метода ссылается на схему по ссылке (а не на встроенную схему), по умолчанию Виддершинс показывает только ссылку на этот параметр. Установите для этого параметра значение true, чтобы развернуть схему и отобразить все свойства в теле запроса. |
| --заголовки | параметры.заголовки | integer | 2 | Установите значение параметра headingLevel в заголовке, чтобы процессоры уценки знали, сколько уровней заголовков следует отображать в оглавлении. В настоящее время поддерживается только Shins, а не Slate, у которого эта функция отсутствует. |
| --omitBody | options.omitBody | boolean | false | По умолчанию Виддершинс включает параметр body в виде строки в таблице параметров перед строками, представляющими поля в тексте. Установите этот параметр, чтобы опустить эту строку параметра тела. |
| --omitHeader | options.omitHeader | boolean | false | Опустите заголовок или заголовок YAML в сгенерированном файле Markdown. |
| --решать | options.resolve | boolean | false | Разрешите внешние $refs, используя source параметр или входной файл в качестве базового местоположения. |
| --shallowSchemas | options.shallowSchemas | boolean | false | При ссылке на схему с помощью $ref не показывайте полное содержимое схемы. |
| Н/Д | options.source | string | Никто | Абсолютное местоположение или URL-адрес исходного файла, который будет использоваться в качестве основы для разрешения относительных ссылок ($refs); требуется, если для параметра options.resolve установлено значение true. Для команд CLI Виддершинс использует входной файл в качестве основы для $refs. |
| --краткое содержание | options.tocSummary | boolean | false | Используйте сводку операции в качестве записи оглавления вместо идентификатора. |
| --useBodyName | options.useBodyName | boolean | Используйте исходное имя параметра для параметра тела OpenAPI 2.0. | |
| -v, --verbose | options.verbose | boolean | false | Увеличьте многословность. |
| -х, --help | options.help | boolean | false | Показать помощь. |
| --версия | параметры.версия | boolean | false | Показать номер версии. |
| -с, --код | options.codeSamples | boolean | false | Опустить сгенерированные примеры кода. |
| --httpsnippet | options.httpsnippet | boolean | false | Используйте httpsnippet для создания примеров кода. |
| -d, --дискавери | options.discovery | boolean | false | Включите данные обнаружения WebAPI Schema.org. |
| -e, --среда | Н/Д | string | Никто | Файл для загрузки параметров конфигурации. |
| -я, --включает | options.includes | string | Никто | Список файлов, которые нужно поместить во include заголовок выходного Markdown. Такие процессоры, как Shins, могут затем импортировать содержимое этих файлов. |
| -л, --язык | options.lang | boolean | false | Создайте список языков для примеров кода на основе языков, используемых в примерах x-code-samples исходного файла. |
| --language_tabs | options.language_tabs | string | (Отличается для каждого типа входа) | Список языковых вкладок для примеров кода, использующих формат языка[:label[:client]], например javascript:JavaScript:request . |
| -m, --maxDepth | options.maxDepth | integer | 10 | Максимальная глубина для отображения примеров схем. |
| -о, --outfile | Н/Д | string | Никто | Файл для записи выходной уценки. Если оставить пустым, Виддершинс отправит выходные данные на стандартный вывод. |
| -р, --сырой | инверсия options.sample | boolean | false | Вывод необработанных схем вместо примеров значений. |
| -s, --search | параметры.поиск | boolean | true | Установите значение параметра search в заголовке, чтобы процессоры Markdown, такие как Slate, включали или не включали поиск в свои выходные данные. |
| -т, --тема | options.theme | string | даркула | Используемая тема выделения синтаксиса. |
| -u, --user_templates | options.user_templates | string | Никто | Каталог для загрузки шаблонов переопределения. |
| -x, --экспериментальный | варианты.экспериментальный | boolean | Используйте httpSnippet для составных медиатипов. | |
| -у, --yaml | options.yaml | boolean | false | Отображение схем JSON в формате YAML. |
| options.templateCallback | function | Никто | function , вызываемая до и после каждого шаблона (только код JavaScript). | |
| options.toc_footers | object | Карта url адресов и description , которые будут добавлены в массив нижних колонтитулов ToC (только код JavaScript). |
В коде Node.JS создайте объект параметров и передайте его функции convert Виддершинса, как в этом примере:
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) конечная точка API считается основанной на исходном URL-адресе, с которого было загружено определение.
Чтобы просмотреть список тем подсветки синтаксиса Highlight-js, нажмите здесь.
Данные обнаружения Schema.org WebAPI включаются, если для параметра discovery выше установлено true . Дополнительную информацию можно найти в группе сообщества W3C WebAPI Discovery.
Виддершинс поддерживает расширение поставщика x-code-samples для полной настройки вашей документации. Альтернативно, вы можете отредактировать образцы кода по умолчанию в подкаталоге templates или переопределить их с помощью параметра user_templates , чтобы указать каталог, содержащий ваши шаблоны.
Виддершинс поддерживает использование нескольких языковых вкладок с одним и тем же языком (т. е. простой Javascript и Node.Js). Чтобы использовать эту поддержку, вы должны использовать Slate (или один из его совместимых портов) версии 1.5.0 или выше.
По умолчанию Виддершинс использует шаблоны в своей папке templates/ для создания вывода Markdown. Чтобы настроить шаблоны, скопируйте некоторые или все из них в папку и передайте их местоположение параметру user_templates .
Шаблоны включают шаблоны .dot и частичные файлы .def . Чтобы переопределить шаблон .dot , необходимо скопировать его и дочерние части .def на которые ссылается шаблон. Аналогично, чтобы переопределить партиал .def , необходимо также скопировать родительский шаблон .dot . Для OpenAPI 3 основным шаблоном является main.dot , а его основными дочерними элементами являются parameters.def , responses.def и callbacks.def .
Это означает, что обычно проще всего скопировать все файлы .dot и .def в каталог пользовательских шаблонов, чтобы не пропустить шаблон или его часть. Чтобы внести изменения из обновлений Виддершинса, вы можете использовать инструмент визуального diff , который может работать в двух каталогах, например Meld или WinMerge.
Шаблоны компилируются с помощью doT.js.
Шаблоны имеют доступ к объекту data с рядом свойств в зависимости от контекста документа. Информацию о параметрах см. в файле README соответствующих шаблонов:
Чтобы напечатать значение параметра или переменной в шаблоне, используйте код {{=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'}}|
{{~}}
Для логики «если/то» используйте код {{? booleanExpression}} для запуска блока кода и код {{?}} для закрытия блока. Например, шаблон main.dot OpenAPI 3 вызывает партиал security.def для отображения информации о схемах безопасности, если спецификация OpenAPI включает раздел securitySchemes :
{{? data.api.components && data.api.components.securitySchemes }}
{{#def.security}}
{{?}}
Вы можете запустить произвольный код JavaScript внутри шаблона, вставив блок кода в фигурные скобки. Например, этот код создает переменную и ссылается на нее с помощью обычного синтаксиса doT.js далее в шаблоне:
{{ {
let message = "Hello!";
} }}
{{=message}}
Параметр templateCallback указывает на функцию, которую Виддершинс вызывает до и после запуска каждого шаблона. Функция обратного вызова получает объект data , содержащий спецификацию, которую обрабатывает Виддершинс; функция должна вернуть этот объект. Вы можете использовать функции обратного вызова, только если вы вызываете Виддершинса из кода JavaScript, а не из командной строки.
Виддершинс передает эти переменные в функцию обратного вызова:
templateName : имя шаблона, например main .stage : вызывает ли Виддершинс функцию обратного вызова до ( pre ) или после ( post ) шаблона.data : объект, содержащий данные, которые обрабатывает Виддершинс. Вы можете изменить объект 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' ) ;
} ) ; Чтобы запустить набор тестов:
node testRunner {path-to-APIs}
В настоящее время тестовая программа ожидает файлы .yaml или .json и была протестирована на соответствие
Публикация в блоге автора Виддершинса.
Пожалуйста, не стесняйтесь добавлять сюда ссылку на документацию по API.
Widdershins хорошо работает со Slate, но для работы исключительно на базе Node.js почему бы не попробовать порт ReSlate?
