widdershins
v4.0.0
OpenAPI / Swagger / AsyncAPI / Slate / ReSlate 호환 마크다운에 대한 Semoasa 정의
restrictions 열( readOnly / writeOnly )이 추가되었습니다.--expandBody 옵션을 사용하여 이전 동작을 복원할 수 있습니다.--maxDepth 옵션을 사용하여 스키마 예제의 깊이를 제한할 수 있습니다. 기본값은 10입니다.main.dot 템플릿을 복사하여 맞춤설정하세요.Authorization 헤더가 포함되어 있습니다. 생략하고 싶다면 여기를 참고하세요.npm i 사용하여 종속성을 설치하거나npm install -g widdershins 전 세계적으로 설치Widdershins는 일반적으로 API 문서 파이프라인의 단계로 사용됩니다. 파이프라인은 OpenAPI 3.x, OpenAPI 2.0(fka Swagger), API Blueprint, AsyncAPI 또는 Semoasa 형식의 API 정의로 시작됩니다. Widdershins는 이 설명을 ReSpec과 함께 사용하기에 적합한 Slate, ReSlate, Shins( 더 이상 사용되지 않음 ) 또는 html과 같은 렌더러 에서 사용하기에 적합한 마크다운으로 변환합니다.
입력 API 정의를 생성해야 하는 경우 사용 가능한 편집기 목록이 유용할 수 있습니다.
더 자세한 문서는 여기에서 확인할 수 있습니다.
node widdershins --search false --language_tabs 'ruby:Ruby' 'python:Python' --summary defs/petstore3.json -o petstore3.md
| CLI 매개변수 이름 | 자바스크립트 매개변수 이름 | 유형 | 기본값 | 설명 |
|---|---|---|---|---|
| --클립보드 | 옵션.클립보드 | boolean | true | 마크다운 프로세서가 클립보드 지원을 포함할 수 있도록 제목의 code_clipboard 속성 값을 설정합니다. |
| --customApiKeyValue | options.customApiKeyValue | string | ApiKey | 생성된 코드 예제에서 API 키로 사용할 사용자 지정 API 키 값을 설정합니다. |
| --expandBody | options.expandBody | boolean | false | 메소드의 requestBody 매개변수가 인라인 스키마가 아닌 참조로 스키마를 참조하는 경우 기본적으로 Widdershins는 이 매개변수에 대한 참조만 표시합니다. 스키마를 확장하고 요청 본문에 모든 속성을 표시하려면 이 옵션을 true로 설정합니다. |
| --제목 | 옵션.제목 | integer | 2 | 마크다운 프로세서가 목차에 표시할 제목 수준 수를 알 수 있도록 헤더에 headingLevel 매개 변수 값을 설정합니다. 현재 이 기능이 부족한 Slate에서는 지원되지 않고 Shins에서만 지원됩니다. |
| --생략본문 | options.omitBody | boolean | false | 기본적으로 Widdershins는 본문의 필드를 나타내는 행 앞에 매개변수 테이블의 행으로 본문 매개변수를 포함합니다. 해당 본문 매개변수 행을 생략하려면 이 매개변수를 설정하세요. |
| --생략헤더 | 옵션.생략헤더 | boolean | false | 생성된 Markdown 파일에서 헤더/YAML 머리말을 생략합니다. |
| --해결하다 | 옵션.해결 | boolean | false | source 매개변수 또는 입력 파일을 기본 위치로 사용하여 외부 $ref를 확인합니다. |
| --shallowSchemas | options.shallowSchemas | boolean | false | $ref를 사용하여 스키마를 참조할 때 스키마의 전체 내용을 표시하지 마세요. |
| 해당 없음 | 옵션.소스 | string | 없음 | 상대 참조($refs)를 확인하기 위한 기반으로 사용할 소스 파일의 절대 위치 또는 URL입니다. options.resolve가 true로 설정된 경우 필요합니다. CLI 명령의 경우 Widdershins는 입력 파일을 $refs의 기본으로 사용합니다. |
| --요약 | options.toc요약 | boolean | false | ID 대신 작업 요약을 목차 항목으로 사용합니다. |
| --useBodyName | options.useBodyName | boolean | OpenAPI 2.0 본문 매개변수에는 원래 매개변수 이름을 사용합니다. | |
| -v, --verbose | 옵션.상세 | boolean | false | 자세한 내용을 늘립니다. |
| -h, --help | 옵션.도움말 | boolean | false | 도움말을 표시합니다. |
| --버전 | 옵션.버전 | boolean | false | 버전 번호를 표시합니다. |
| -c, --코드 | options.code샘플 | boolean | false | 생성된 코드 샘플을 생략합니다. |
| --httpsnippet | options.httpsnippet | boolean | false | httpsnippet을 사용하여 코드 샘플을 생성하세요. |
| -d, --발견 | 옵션.발견 | boolean | false | Schema.org WebAPI 검색 데이터를 포함합니다. |
| -e, --환경 | 해당 없음 | string | 없음 | 구성 옵션을 로드할 파일입니다. |
| -i, --포함 | 옵션.포함 | string | 없음 | 출력 Markdown의 include 헤더에 넣을 파일 목록입니다. 그런 다음 Shins와 같은 프로세서는 이러한 파일의 내용을 가져올 수 있습니다. |
| -l, --lang | 옵션.lang | boolean | false | 소스 파일의 x-code-samples 예제에 사용된 언어를 기반으로 코드 샘플의 언어 목록을 생성합니다. |
| --언어_탭 | 옵션.언어_탭 | string | (입력종류에 따라 다름) | javascript:JavaScript:request 와 같이 언어[:label[:client]] 형식을 사용하는 코드 샘플의 언어 탭 목록입니다. |
| -m, --maxDepth | 옵션.최대 깊이 | integer | 10 | 스키마 예시에 표시할 최대 깊이입니다. |
| -o, --outfile | 해당 없음 | string | 없음 | 출력 마크다운을 쓸 파일입니다. 공백으로 두면 Widdershins는 출력을 stdout으로 보냅니다. |
| -r, --raw | options.sample의 반대 | boolean | false | 예시 값 대신 원시 스키마를 출력합니다. |
| -s, --search | 옵션.검색 | boolean | true | Slate와 같은 마크다운 프로세서가 출력에 검색을 포함할지 여부를 헤더에 있는 search 매개변수 값을 설정합니다. |
| -t, --테마 | 옵션.테마 | string | 암울라 | 사용할 구문 강조 테마입니다. |
| -u, --user_templates | 옵션.사용자_템플릿 | string | 없음 | 재정의 템플릿을 로드할 디렉터리입니다. |
| -x, --실험적 | 옵션.실험적 | boolean | 멀티파트 미디어 유형에는 httpSnippet을 사용하세요. | |
| -y, --yaml | 옵션.yaml | boolean | false | JSON 스키마를 YAML 형식으로 표시합니다. |
| 옵션.템플릿콜백 | function | 없음 | 각 템플릿 전후에 호출되는 function 입니다(JavaScript 코드만 해당). | |
| 옵션.toc_footers | object | ToC 바닥글 배열에 추가할 url 및 description 의 맵입니다(JavaScript 코드만 해당). |
Node.JS 코드에서 다음 예제와 같이 옵션 객체를 생성하고 이를 Widdershins 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 .언어_tabs를 재정의할 수 있습니다.
options . language_tabs = [ { 'go' : 'Go' } , { 'http' : 'HTTP' } , { 'javascript' : 'JavaScript' } , { 'javascript--node' : 'Node.JS' } , { 'python' : 'Python' } , { 'ruby' : 'Ruby' } ] ; --environment 옵션은 JSON 또는 YAML 형식의 options 객체를 지정합니다. 예를 들면 다음과 같습니다.
{
"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 를 사용할 수 있습니다. 이를 간단히 달성하려면 포함된 whiteboard_env.json 파일을 사용하여 --environment 옵션을 사용하세요.
httpsnippet 옵션을 사용하여 코드 샘플을 생성하는 경우 options.language_clients .언어_clients를 재정의하여 각 언어에 대한 요청을 수행하는 데 사용되는 클라이언트 라이브러리를 지정할 수 있습니다.
options . language_clients = [ { 'shell' : 'curl' } , { 'node' : 'request' } , { 'java' : 'unirest' } ] ; 구문 강조 표시에 필요한 마크다운 이름과 httpsnippet 필수 대상 간에 언어 이름이 다른 경우 둘 다 markdown--target 형식으로 지정할 수 있습니다.
httpsnippet에서 지원되는 언어 및 클라이언트 목록을 보려면 여기를 클릭하세요.
loadedFrom 옵션은 OpenAPI/Swagger 정의가 호스트를 지정하지 않고 (OpenAPI 사양에 따라) API 엔드포인트가 정의가 로드된 소스 URL을 기반으로 하는 것으로 간주되는 경우에만 필요합니다.
하이라이트-js 구문 강조 테마 목록을 보려면 여기를 클릭하세요.
위의 discovery 옵션이 true 설정된 경우 Schema.org WebAPI 검색 데이터가 포함됩니다. 자세한 내용은 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 업데이트에서 변경 사항을 가져오려면 Meld 또는 WinMerge와 같은 두 디렉터리에서 실행할 수 있는 시각적 diff 도구를 사용할 수 있습니다.
템플릿은 doT.js로 컴파일됩니다.
템플릿은 문서 컨텍스트를 기반으로 하는 다양한 속성을 사용하여 data 개체에 액세스할 수 있습니다. 매개변수에 대한 자세한 내용은 해당 템플릿에 대한 README 파일을 참조하세요.
템플릿의 매개변수 또는 변수 값을 인쇄하려면 {{=parameterName}} 코드를 사용하세요. 예를 들어, OpenAPI 3 사양의 제목( info.title 필드에서)을 인쇄하려면 {{=data.api.info.title}} 코드를 사용하세요.
배열의 값을 반복하려면 {{~ arrayName :tempVariable}} 코드를 사용하여 루프를 시작하고 코드 {{~}} 사용하여 루프를 닫습니다. 예를 들어 OpenAPI 3 부분 parameters.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 템플릿은 OpenAPI 사양에 securitySchemes 섹션이 포함된 경우 security.def 부분을 호출하여 보안 체계에 대한 정보를 표시합니다.
{{? data.api.components && data.api.components.securitySchemes }}
{{#def.security}}
{{?}}
중괄호 안에 코드 블록을 삽입하여 템플릿 내에서 임의의 JavaScript를 실행할 수 있습니다. 예를 들어, 다음 코드는 변수를 생성하고 나중에 템플릿에서 일반적인 doT.js 구문을 사용하여 이를 참조합니다.
{{ {
let message = "Hello!";
} }}
{{=message}}
templateCallback 매개변수는 각 템플릿이 실행되기 전후에 Widdershins가 호출하는 함수를 가리킵니다. 콜백 함수는 Widdershins가 처리하는 사양이 포함된 data 개체를 받습니다. 함수는 이 객체를 반환해야 합니다. 명령줄이 아닌 JavaScript 코드에서 Widdershins를 호출하는 경우에만 콜백 함수를 사용할 수 있습니다.
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' ) ;
} ) ; 테스트 스위트를 실행하려면:
node testRunner {path-to-APIs}
테스트 하네스는 현재 .yaml 또는 .json 파일을 예상하며 이에 대해 테스트되었습니다.
Widdershins 작성자의 블로그 게시물입니다.
여기에 API 문서에 대한 링크를 자유롭게 추가하세요.
Widdershins Slate와 잘 작동하지만 Node.js 기반 경험만 원한다면 ReSlate 포트를 사용해 보는 것은 어떨까요?
