swagger editor
v4.14.0 Released!
⏰️ Swagger Editor의 차세대 버전을 찾고 계십니까?
SwaggerEditor는 이제 두 가지 주요 릴리스 채널로 출시됩니다.
SwaggerEditor@5 만이 OpenAPI 3.1.0을 지원합니다. SwaggerEditor@4는 OpenAPI 3.1.0 지원을 받지 않으며 현재 레거시로 간주됩니다. 계획은 지속적으로 SwaggerEditor@5로 완전히 마이그레이션하고 향후 SwaggerEditor@4를 더 이상 사용하지 않는 것입니다.
?️ Swagger Editor의 이전 버전을 찾고 계십니까? 2.x 또는 3.x 분기를 참조하세요.
Swagger Editor를 사용하면 브라우저 내에서 JSON 또는 YAML 형식의 OpenAPI API 정의 (OpenAPI 2.0 및 OpenAPI 3.0.3)를 편집하고 문서를 실시간으로 미리 볼 수 있습니다. 그런 다음 유효한 OpenAPI 정의를 생성하고 전체 Swagger 도구(코드 생성, 문서 등)와 함께 사용할 수 있습니다.
처음부터 새로 작성된 새로운 버전이므로 몇 가지 알려진 문제와 구현되지 않은 기능이 있습니다. 자세한 내용은 알려진 문제 섹션을 확인하세요.
이 저장소는 두 가지 NPM 모듈에 게시됩니다.
단일 페이지 애플리케이션을 구축하는 경우 swagger-editor-dist 훨씬 크기 때문에 swagger-editor 사용하는 것이 좋습니다.
Swagger Editor는 Scarf를 사용하여 익명화된 설치 분석을 수집합니다. 이러한 분석은 이 라이브러리의 관리자를 지원하는 데 도움이 되며 설치 중에만 실행됩니다. 선택 해제하려면 프로젝트의 package.json 에서 scarfSettings.enabled 필드를 false 로 설정하면 됩니다.
// package.json
{
// ...
"scarfSettings": {
"enabled": false
}
// ...
}
또는 npm 패키지를 설치하는 환경의 일부로 SCARF_ANALYTICS 환경 변수를 false 로 설정할 수 있습니다(예: SCARF_ANALYTICS=false npm install ).
아래 스크립트는 프로젝트의 루트 디렉터리에 npm run <script name> 입력하여 실행할 수 있습니다.
| 스크립트 이름 | 설명 |
|---|---|
dev | 포트 3200에서 핫 리로딩 개발 서버를 생성합니다. |
deps-check | Swagger Editors의 종속성에 대한 크기 및 라이선스 보고서를 생성합니다. |
lint | ESLint 스타일 오류 및 경고를 보고합니다. |
lint-errors | 경고 없이 ESLint 스타일 오류를 보고합니다. |
lint-fix | 스타일 오류를 자동으로 수정해 봅니다. |
watch | 소스 코드가 변경되면 /dist 에 코어 파일을 다시 빌드합니다. npm link 에 유용합니다. |
| 스크립트 이름 | 설명 |
|---|---|
build | 새로운 JS 및 CSS 자산 세트를 빌드하고 /dist 에 출력합니다. |
build:bundle | swagger-editor-bundle.js 만 빌드합니다(commonJS). |
build:core | swagger-editor.(js|css) 만 빌드합니다(commonJS). |
build:standalone | swagger-editor-standalone-preset.js 만 빌드합니다(commonJS). |
build:stylesheets | swagger-editor.css 만 빌드하세요. |
build:es:bundle | swagger-editor-es-bundle.js 만 빌드하세요(es2015). |
build:es:bundle:core | swagger-editor-es-bundle-core.js 만 빌드하세요(es2015). |
| 스크립트 이름 | 설명 |
|---|---|
test | Node에서 단위 테스트를 실행하고, Cypress 엔드투엔드 테스트를 실행하고, 오류 전용 모드에서 ESLint를 실행하세요. |
test:unit-mocha | Node.js에서 Mocha 기반 단위 테스트를 실행하세요. |
test:unit-jest | Node.js에서 Jest 기반 단위 테스트를 실행하세요. |
e2e | Cypress로 엔드투엔드 브라우저 테스트를 실행하세요. |
lint | ESLint 테스트 실행 |
test:artifact | Jest에서 번들 아티팩트 테스트 목록 실행 |
test:artifact:umd:bundle | swagger-editor-bundle 내보내기를 함수로 확인하는 단위 테스트 실행 |
test:artifact:es:bundle | swagger-editor-es-bundle 내보내기를 함수로 확인하는 단위 테스트 실행 |
test:artifact:es:bundle:core | swagger-editor-es-bundle-core 내보내기를 함수로 확인하는 단위 테스트 실행 |
$ npm i --legacy-peer-deps Node.js와 npm이 설치되어 있는 경우 npm start 실행하여 정적 서버를 가동할 수 있습니다.
그렇지 않으면 브라우저의 파일 시스템에서 index.html 직접 열 수 있습니다.
Swagger Editor의 코드를 변경하려면 npm run dev 를 통해 Webpack 핫 리로딩 개발 서버를 시작할 수 있습니다.
Swagger Editor는 최신 버전의 Chrome, Safari, Firefox 및 Edge에서 작동합니다.
마이그레이션을 돕기 위해 현재 3.X에서 알려진 문제는 다음과 같습니다. 이 목록은 정기적으로 업데이트되며 이전 버전에서 구현되지 않은 기능은 포함되지 않습니다.
DockerHub에 Docker 이미지가 게시되어 있습니다.
이를 사용하려면 다음을 실행하십시오.
docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor
이렇게 하면 컴퓨터의 포트 80에서 Swagger Editor(분리 모드)가 실행되므로 브라우저에서 http://localhost 로 이동하여 열 수 있습니다.
docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" swaggerapi/swagger-editor
json 또는 yaml 정의 파일을 제공할 수 있습니다. docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor
참고: URL 및 SWAGGER_FILE 환경 변수가 모두 설정된 경우 URL 우선순위를 가지며 SWAGGER_FILE 무시됩니다.
BASE_URL 변수를 통해 다른 기본 URL을 지정할 수 있습니다. 예를 들어 애플리케이션을 http://localhost/swagger-editor/ 에서 사용할 수 있도록 하려는 경우: docker run -d -p 80:8080 -e BASE_URL=/swagger-editor swaggerapi/swagger-editor
PORT 변수를 통해 다른 포트를 지정할 수 있습니다. 기본값은 8080 입니다. docker run -d -p 80:80 -e PORT=80 swaggerapi/swagger-editor
GTM 변수를 통해 Google 태그 관리자 ID를 지정할 수 있습니다. docker run -d -p 80:8080 -e GTM=GTM-XXXXXX swaggerapi/swagger-editor
다음 환경 변수를 사용하여 Swagger Editor에서 사용하는 다양한 엔드포인트를 사용자 정의할 수도 있습니다. 예를 들어, 이는 자체 Swagger 생성기 서버가 있는 경우 유용할 수 있습니다.
| 환경변수 | 기본값 |
|---|---|
URL_SWAGGER2_GENERATOR | https://generator.swagger.io/api/swagger.json |
URL_OAS3_GENERATOR | https://generator3.swagger.io/openapi.json |
URL_SWAGGER2_CONVERTER | https://converter.swagger.io/api/convert |
Codegen 기능(서버 생성 및 클라이언트 생성) 없이 로컬에서 Swagger Editor를 실행하려면 위의 환경 변수를 null ( URL_SWAGGER2_CONVERTER=null )로 설정할 수 있습니다.
머신에서 체크아웃된 코드를 사용하여 Docker 이미지를 빌드하고 실행하려면 프로젝트의 루트 디렉터리에서 다음을 실행하세요.
# Install npm packages (if needed)
npm install
# Build the app
npm run build
# Build an image
docker build -t swagger-editor .
# Run the container
docker run -d -p 80:8080 swagger-editor
그런 다음 브라우저에서 http://localhost 로 이동하여 앱을 볼 수 있습니다.
OpenAPI 문서 가져오기
기여
중요한
이전 버전에서는 구체적으로 React >=17 <18 을 참조합니다.
기본적으로 swagger-editor@4 npm 패키지는 최신 버전의 React@18과 함께 제공됩니다. 이전 버전의 React에서는 swagger-editor@4 npm 패키지를 사용할 수 있습니다.
내 애플리케이션이 swagger-editor@4 npm 패키지와 통합되고 [email protected]를 사용한다고 가정해 보겠습니다.
내 React 버전을 사용하려면 swagger-editor@4 npm 패키지에 알리려면 npm 재정의를 사용해야 합니다.
{
"dependencies" : {
"react" : " =17.0.2 " ,
"react-dom" : " =17.0.2 "
},
"overrides" : {
"swagger-editor" : {
"react" : " $react " ,
"react" : " $react-dom " ,
"react-redux" : " ^8 "
}
}
}메모
React 및 ReactDOM 재정의는 종속성에 대한 참조로 정의됩니다. React-redux@9 는 React >= 18 만 지원하므로, React-redux@8 을 사용해야 합니다.
내 특정 React 버전을 사용해야 한다는 것을 swagger-editor@4 npm 패키지에 알리려면 원사 해상도를 사용해야 합니다.
{
"dependencies" : {
"react" : " 17.0.2 " ,
"react-dom" : " 17.0.2 "
},
"resolutions" : {
"swagger-editor/react" : " 17.0.2 " ,
"swagger-editor/react-dom" : " 17.0.2 " ,
"swagger-editor/react-redux" : " ^8 "
}
}메모
React 및 ReactDOM 해결은 종속성에 대한 참조로 정의될 수 없습니다. 불행하게도 Yarn은 npm 처럼 $react 또는 $react-dom 과 같은 앨리어싱을 지원하지 않습니다. 정확한 버전을 지정해야 합니다.
공개 문제 추적기를 사용하는 대신 [email protected]로 이메일을 보내 보안 관련 문제나 취약점을 공개해 주십시오.
